Mercurial > mplayer.hg
changeset 21521:b210a229fbcb
General reformatting round:
- fix some " -> "
- reindent with more consistency
- visual markup of <sect?> tags
- break overly long lines
- add missing <replaceable> tags in examples
- cola truck standing by
| author | torinthiel |
|---|---|
| date | Fri, 08 Dec 2006 11:38:06 +0000 |
| parents | 0977cf2eb136 |
| children | 312b3ad1a31a |
| files | DOCS/xml/en/audio.xml DOCS/xml/en/bugreports.xml DOCS/xml/en/bugs.xml DOCS/xml/en/cd-dvd.xml DOCS/xml/en/codecs.xml DOCS/xml/en/containers.xml DOCS/xml/en/documentation.xml DOCS/xml/en/encoding-guide.xml DOCS/xml/en/faq.xml DOCS/xml/en/history.xml DOCS/xml/en/install.xml DOCS/xml/en/mencoder.xml DOCS/xml/en/ports.xml DOCS/xml/en/radio.xml DOCS/xml/en/skin.xml DOCS/xml/en/tvinput.xml DOCS/xml/en/usage.xml DOCS/xml/en/video.xml |
| diffstat | 18 files changed, 5521 insertions(+), 4873 deletions(-) [+] |
line wrap: on
line diff
--- a/DOCS/xml/en/audio.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/audio.xml Fri Dec 08 11:38:06 2006 +0000 @@ -35,23 +35,28 @@ </para> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="troubleshooting"> <title>Troubleshooting</title> <para>Some notes:</para> <para> - If you have ALSA version 0.5, then you almost always have to use - <option>-ao alsa5</option>, since ALSA 0.5 has buggy OSS emulation code, - and will <emphasis role="bold">crash <application>MPlayer</application></emphasis> - with a message like this: - <screen> -DEMUXER: Too many (945 in 8390980 bytes) video packets in the buffer!<!-- ---></screen> +If you have ALSA version 0.5, then you almost always have to use +<option>-ao alsa5</option>, since ALSA 0.5 has buggy OSS emulation code, +and will <emphasis role="bold">crash <application>MPlayer</application></emphasis> +with a message like this: +<screen> +DEMUXER: Too many (945 in 8390980 bytes) video packets in the buffer! +</screen> </para> + <para> - If the sound clicks when playing from CD-ROM, turn on IRQ unmasking as - described in the <link linkend="drives">CD-ROM</link> section. +If the sound clicks when playing from CD-ROM, turn on IRQ unmasking as +described in the <link linkend="drives">CD-ROM</link> section. </para> </sect1>
--- a/DOCS/xml/en/bugreports.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/bugreports.xml Fri Dec 08 11:38:06 2006 +0000 @@ -2,6 +2,7 @@ <!-- $Revision$ --> <appendix id="bugreports"> <title>How to report bugs</title> + <para> Good bug reports are a very valuable contribution to the development of any software project. But just like writing good software, good problem reports @@ -11,8 +12,14 @@ that you have to provide <emphasis role="bold">all</emphasis> of the information we request and follow the instructions in this document closely. </para> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_security"> <title>Report security releated bugs</title> + <para> In case you have found an exploitable bug and you would like to do the right thing and let us fix it before you disclose it, we would be happy @@ -25,33 +32,48 @@ send that one with another mail. </para> </sect1> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_fix"> <title>How to fix bugs</title> + <para> If you feel have the necessary skills you are invited to have a go at fixing the bug yourself. Or maybe you already did that? Please read -<ulink url="../../tech/patches.txt">this short document</ulink> to find out how to -get your code included in <application>MPlayer</application>. The people on the +<ulink url="../../tech/patches.txt">this short document</ulink> to find out how +to get your code included in <application>MPlayer</application>. The people on +the <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-dev-eng">MPlayer-dev-eng</ulink> mailing list will assist you if you have questions. </para> </sect1> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_regression_test"> <title>How to do regression testing using Subversion</title> + <para> A problem that can happen sometimes is 'it used to work before, now it doesn't anymore...'. Here is a step by step procedure to try to pinpoint when the problem occurred. This is <emphasis role="bold">not</emphasis> for casual users. </para> + <para> First, you'd need to fetch MPlayer's source tree from Subversion. Instructions can be found at the bottom of <ulink url="http://www.mplayerhq.hu/dload.html">this page</ulink>. </para> + <para> -You will have now in the mplayer/ directory an image of the Subversion tree, on the -client side. +You will have now in the mplayer/ directory an image of the Subversion tree, on +the client side. Now update this image to the date you want: <screen> cd mplayer/ @@ -62,6 +84,7 @@ according to the date at which they were committed, as in the <ulink url="http://lists.mplayerhq.hu/pipermail/mplayer-cvslog/">MPlayer-cvslog archive</ulink>. </para> + <para> Now proceed as for a normal update: <screen> @@ -69,6 +92,7 @@ make </screen> </para> + <para> If any non-programmer reads this, the fastest method to get at the point where the problem occurred is to use a binary search — that is, @@ -79,6 +103,7 @@ If yes, go back to the first of April; if not, go to the first of October, and so on. </para> + <para> If you have lot of free hard disk space (a full compile currently takes 100 MB, and around 300-350 MB if debugging symbols are enabled), copy the @@ -89,6 +114,7 @@ source tree, you will have to recompile everything in it when you come back to the present.) </para> + <para> When you have found the day where the problem happened, continue the search using the mplayer-cvslog archive (sorted by date) and a more precise svn @@ -98,6 +124,7 @@ </screen> This will allow you to easily find the exact patch that did it. </para> + <para> If you find the patch that is the cause of the problem, you have almost won; report about it to the @@ -110,80 +137,102 @@ the bug is :-). </para> </sect1> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_report"> <title>How to report bugs</title> + <para> -First of all please try the latest Subversion version of <application>MPlayer</application> +First of all please try the latest Subversion version of +<application>MPlayer</application> as your bug might already be fixed there. Development moves extremely fast, -most problems in official releases are reported within days or even hours, so -please use <emphasis role="bold">only Subversion</emphasis> to report bugs. This -includes binary packages of <application>MPlayer</application>. Subversion -instructions can be found at the bottom of +most problems in official releases are reported within days or even hours, +so please use <emphasis role="bold">only Subversion</emphasis> to report bugs. +This includes binary packages of <application>MPlayer</application>. +Subversion instructions can be found at the bottom of <ulink url="http://www.mplayerhq.hu/dload.html">this page</ulink> or in the README. If this did not help please refer to the list of -<link linkend="bugs">known bugs</link> and the rest of the documentation. If your -problem is not known or not solvable by our instructions, then please report the bug. +<link linkend="bugs">known bugs</link> and the rest of the documentation. +If your problem is not known or not solvable by our instructions, +then please report the bug. </para> <para> Please do not send bug reports privately to individual developers. This is -community work and thus there might be several people interested in it. Sometimes -other users already experienced your troubles and know how to circumvent a problem -even if it is a bug in <application>MPlayer</application> code. +community work and thus there might be several people interested in it. +Sometimes other users already experienced your troubles and know how to +circumvent a problem even if it is a bug in <application>MPlayer</application> +code. </para> <para> -Please describe your problem in as much detail as possible. Do a little detective -work to narrow down the circumstances under which the problem occurs. Does the bug -only show up in certain situations? Is it specific to certain files or file types? -Does it occur with only one codec or is it codec independent? Can you reproduce it -with all output drivers? The more information you provide the better are our -chances at fixing your problem. Please do not forget to also include the valuable -information requested below, we will be unable to properly diagnose your problem -otherwise. +Please describe your problem in as much detail as possible. Do a little +detective work to narrow down the circumstances under which the problem occurs. +Does the bug only show up in certain situations? Is it specific to certain +files or file types? Does it occur with only one codec or is it codec +independent? Can you reproduce it with all output drivers? The more information +you provide the better are our chances at fixing your problem. Please do not +forget to also include the valuable information requested below, we will be +unable to properly diagnose your problem otherwise. </para> <para> An excellent and well written guide to asking questions in public forums is -<ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask -Questions The Smart Way</ulink> by <ulink url="http://www.catb.org/~esr/">Eric S. Raymond</ulink>. +<ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask Questions The Smart Way</ulink> +by <ulink url="http://www.catb.org/~esr/">Eric S. Raymond</ulink>. There is another called -<ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report -Bugs Effectively</ulink> by <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</ulink>. +<ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report Bugs Effectively</ulink> +by <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</ulink>. If you follow these guidelines you should be able to get help. But please understand that we all follow the mailing lists voluntarily in our free time. We are very busy and cannot guarantee that you will get a solution for your problem or even an answer. </para> +</sect1> -</sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="bugreports_where"> <title>Where to report bugs</title> + <para> Subscribe to the MPlayer-users mailing list: <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-users"/> and send your bug report to <ulink url="mailto:mplayer-users@mplayerhq.hu"/> where you can discuss it. </para> + <para> If you prefer, you can use our brand-new <ulink url="http://bugzilla.mplayerhq.hu/">Bugzilla</ulink> instead. </para> + <para> -The language of this list is <emphasis role="bold">English</emphasis>. Please follow the standard -<ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink> and -<emphasis role="bold">do not send HTML mail</emphasis> to any of our mailing lists. You will only get ignored or +The language of this list is <emphasis role="bold">English</emphasis>. +Please follow the standard +<ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink> +and <emphasis role="bold">do not send HTML mail</emphasis> to any of our +mailing lists. You will only get ignored or banned. If you do not know what HTML mail is or why it is evil, read this -<ulink url="http://expita.com/nomime.html">fine document</ulink>. It explains all -the details and has instructions for turning HTML off. Also note that we will not -individually CC (carbon-copy) people so it is a good idea to subscribe to actually -receive your answer. +<ulink url="http://expita.com/nomime.html">fine document</ulink>. +It explains all the details and has instructions for turning HTML off. Also +note that we will not individually CC (carbon-copy) people so it is a good idea +to subscribe to actually receive your answer. </para> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_what"> <title>What to report</title> + <para> You may need to include log, configuration or sample files in your bug report. If some of them are quite big then it is better to upload them to our @@ -193,54 +242,56 @@ you have something bigger you have to compress or upload it. </para> +<!-- ********** --> + <sect2 id="bugreports_system"> <title>System Information</title> + <para> <itemizedlist> <listitem><para> -Your Linux distribution or operating system and version e.g.: + Your Linux distribution or operating system and version e.g.: <itemizedlist> <listitem><para>Red Hat 7.1</para></listitem> <listitem><para>Slackware 7.0 + devel packs from 7.1 ...</para></listitem> </itemizedlist> </para></listitem> <listitem><para> -kernel version: -<screen>uname -a</screen> + kernel version: + <screen>uname -a</screen> </para></listitem> <listitem><para> -libc version: -<screen>ls -l /lib/libc[.-]*</screen> + libc version: + <screen>ls -l /lib/libc[.-]*</screen> </para></listitem> <listitem><para> -gcc and ld versions: -<screen> + gcc and ld versions: + <screen> gcc -v -ld -v -</screen> +ld -v<!-- + --></screen> </para></listitem> <listitem><para> -binutils version: -<screen> -as --version -</screen> + binutils version: + <screen>as --version</screen> </para></listitem> <listitem><para> -If you have problems with fullscreen mode: + If you have problems with fullscreen mode: <itemizedlist> <listitem><para>Window manager type and version</para></listitem> </itemizedlist> </para></listitem> <listitem><para> -If you have problems with XVIDIX: + If you have problems with XVIDIX: <itemizedlist> - <listitem><para>X colour depth: -<screen>xdpyinfo | grep "depth of root"</screen> - </para></listitem> + <listitem><para> + X colour depth: + <screen>xdpyinfo | grep "depth of root"</screen> + </para></listitem> </itemizedlist> </para></listitem> <listitem><para> -If only the GUI is buggy: + If only the GUI is buggy: <itemizedlist> <listitem><para>GTK version</para></listitem> <listitem><para>GLIB version</para></listitem> @@ -252,23 +303,26 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_hardware"> <title>Hardware and drivers</title> + <para> <itemizedlist> <listitem><para> -CPU info (this works on Linux only): -<screen>cat /proc/cpuinfo</screen> + CPU info (this works on Linux only): + <screen>cat /proc/cpuinfo</screen> </para></listitem> <listitem><para> -Video card manufacturer and model, e.g.: + Video card manufacturer and model, e.g.: <itemizedlist> <listitem><para>ASUS V3800U chip: nVidia TNT2 Ultra pro 32MB SDRAM</para></listitem> <listitem><para>Matrox G400 DH 32MB SGRAM</para></listitem> </itemizedlist> </para></listitem> <listitem><para> -Video driver type & version, e.g.: + Video driver type & version, e.g.: <itemizedlist> <listitem><para>X built-in driver</para></listitem> <listitem><para>nVidia 0.9.623</para></listitem> @@ -277,7 +331,7 @@ </itemizedlist> </para></listitem> <listitem><para> -Sound card type & driver, e.g.: + Sound card type & driver, e.g.: <itemizedlist> <listitem><para>Creative SBLive! Gold with OSS driver from oss.creative.com</para></listitem> <listitem><para>Creative SB16 with kernel OSS drivers</para></listitem> @@ -285,14 +339,17 @@ </itemizedlist> </para></listitem> <listitem><para> -If in doubt include <command>lspci -vv</command> output on Linux systems. + If in doubt include <command>lspci -vv</command> output on Linux systems. </para></listitem> </itemizedlist> </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_configure"> <title>Configure problems</title> + <para> If you get errors while running <command>./configure</command>, or autodetection of something fails, read <filename>configure.log</filename>. You may find the @@ -305,57 +362,74 @@ <sect2 id="bugreports_compilation"> <title>Compilation problems</title> + <para> Please include these files: <itemizedlist> -<listitem><para>config.h</para></listitem> -<listitem><para>config.mak</para></listitem> + <listitem><para>config.h</para></listitem> + <listitem><para>config.mak</para></listitem> </itemizedlist> </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_playback"> <title>Playback problems</title> + <para> -Please include the output of <application>MPlayer</application> at verbosity level -1, but remember to <emphasis role="bold">not truncate the output</emphasis> when +Please include the output of <application>MPlayer</application> at verbosity +level 1, but remember to +<emphasis role="bold">not truncate the output</emphasis> when you paste it into your mail. The developers need all of the messages to properly diagnose a problem. You can direct the output into a file like this: -<screen>mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> > mplayer.log 2>&1</screen> +<screen> +mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> > mplayer.log 2>&1 +</screen> </para> <para> -If your problem is specific to one or more files, then please upload the offender(s) to: +If your problem is specific to one or more files, +then please upload the offender(s) to: <ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/"/> </para> <para> Also upload a small text file having the same base name as your file with a .txt -extension. Describe the problem you are having with the particular file there and -include your email address as well as the output of <application>MPlayer</application> -at verbosity level 1. Usually the first 1-5 MB of a file are enough to reproduce +extension. Describe the problem you are having with the particular file there +and include your email address as well as the output of +<application>MPlayer</application> at verbosity level 1. +Usually the first 1-5 MB of a file are enough to reproduce the problem, but to be sure we ask you to: -<screen>dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5</screen> -It will take the first five megabytes of '<emphasis role="bold">your-file</emphasis>' -and write it to '<emphasis role="bold">small-file</emphasis>'. Then try again on +<screen> +dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5 +</screen> +It will take the first five megabytes of +'<emphasis role="bold">your-file</emphasis>' and write it to +'<emphasis role="bold">small-file</emphasis>'. Then try again on this small file and if the bug still shows up your sample is sufficient for us. Please <emphasis role="bold">do not ever</emphasis> send such files via mail! Upload it, and send only the path/filename of the file on the FTP-server. If the -file is accessible on the net, then sending the <emphasis role="bold">exact</emphasis> -URL is sufficient. +file is accessible on the net, then sending the +<emphasis role="bold">exact</emphasis> URL is sufficient. </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_crash"> <title>Crashes</title> + <para> You have to run <application>MPlayer</application> inside <command>gdb</command> -and send us the complete output or if you have a <filename>core</filename> dump of -the crash you can extract useful information from the Core file. Here's how: +and send us the complete output or if you have a <filename>core</filename> dump +of the crash you can extract useful information from the Core file. Here's how: </para> + <sect3 id="bugreports_debug"> <title>How to conserve information about a reproducible crash</title> + <para> Recompile <application>MPlayer</application> with debugging code enabled: <screen> @@ -365,9 +439,11 @@ and then run <application>MPlayer</application> within gdb using: <screen>gdb ./mplayer</screen> You are now within gdb. Type: -<screen>run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable></screen> -and reproduce your crash. As soon as you did it, gdb will return you to the command -line prompt where you have to enter +<screen> +run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable> +</screen> +and reproduce your crash. As soon as you did it, gdb will return you to the +command line prompt where you have to enter <screen> bt disass $pc-32 $pc+32 @@ -376,8 +452,10 @@ </para> </sect3> + <sect3 id="bugreports_core"> <title>How to extract meaningful information from a core dump</title> + <para> Create the following command file: <screen> @@ -386,30 +464,38 @@ info all-registers </screen> Then simply execute this command: -<screen>gdb mplayer --core=core -batch --command=<replaceable>command_file</replaceable> > mplayer.bug</screen> +<screen> +gdb mplayer --core=core -batch --command=command_file > mplayer.bug +</screen> </para> </sect3> </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_advusers"> <title>I know what I am doing...</title> + <para> -If you created a proper bug report following the steps above and you are confident -it is a bug in <application>MPlayer</application>, not a compiler problem or broken -file, you have already read the documentation and you could not find a solution, -your sound drivers are OK, then you might want to subscribe to the MPlayer-advusers -list and send your bug report there to get a better and faster answer. +If you created a proper bug report following the steps above and you are +confident it is a bug in <application>MPlayer</application>, not a compiler +problem or broken file, you have already read the documentation and you could +not find a solution, your sound drivers are OK, then you might want to +subscribe to the MPlayer-advusers list and send your bug report there to get +a better and faster answer. </para> <para> Please be advised that if you post newbie questions or questions answered in the -manual there, you will be ignored or flamed instead of getting an appropriate answer. -So do not flame us and subscribe to -advusers only if you really know what you are -doing and feel like being an advanced <application>MPlayer</application> user or -developer. If you meet these criteria it should not be difficult to find out how to subscribe... +manual there, you will be ignored or flamed instead of getting an appropriate +answer. So do not flame us and subscribe to -advusers only if you really know +what you are doing and feel like being an advanced +<application>MPlayer</application> user or developer. If you meet these +criteria it should not be difficult to find out how to subscribe... </para> - </sect1> </appendix>
--- a/DOCS/xml/en/bugs.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/bugs.xml Fri Dec 08 11:38:06 2006 +0000 @@ -3,147 +3,184 @@ <appendix id="bugs"> <title>Known bugs</title> - <sect1 id="bugs-special"> <title>Special system/CPU-specific bugs/problems</title> + <itemizedlist> <listitem> -<para>SIGILL (signal 4) on P3 using 2.2.x kernels:</para> -<para>Problem: kernel 2.2.x doesn't have proper (working) SSE support</para> -<para>Solution: upgrade kernel to 2.4.x</para> -<para>Workaround: <command>./configure --disable-sse</command></para> + <para>SIGILL (signal 4) on P3 using 2.2.x kernels:</para> + <para>Problem: kernel 2.2.x doesn't have proper (working) SSE support</para> + <para>Solution: upgrade kernel to 2.4.x</para> + <para>Workaround: <command>./configure --disable-sse</command></para> </listitem> <listitem> -<para>General SIGILL (signal 4):</para> -<para>Problem: you compiled and run <application>MPlayer</application> on -different machines (for example compiled on P3 and running on Celeron)</para> -<para>Solution: compile <application>MPlayer</application> on the same machine -where you will use it!</para> -<para>Workaround: You can forget all this by configuring with the -<option>--enable-runtime-cpudetection</option> option or you can -disable particular CPU instruction sets with more specific options (like -<option>--disable-mmx</option>, <option>--disable-3dnow</option>, etc). -</para> + <para>General SIGILL (signal 4):</para> + <para> + Problem: you compiled and run <application>MPlayer</application> on + different machines (for example compiled on P3 and running on Celeron) + </para> + <para> + Solution: compile <application>MPlayer</application> on the same machine + where you will use it! + </para> + <para> + Workaround: You can forget all this by configuring with the + <option>--enable-runtime-cpudetection</option> option or you can + disable particular CPU instruction sets with more specific options (like + <option>--disable-mmx</option>, <option>--disable-3dnow</option>, etc). + </para> </listitem> <listitem> -<para>Crashes when dumping streams:</para> -<para>Problem: core dump</para> -<para>Solution: Don't panic. Make sure you know where your towel is.</para> + <para>Crashes when dumping streams:</para> + <para>Problem: core dump</para> + <para>Solution: Don't panic. Make sure you know where your towel is.</para> </listitem> </itemizedlist> </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugs-audio"> <title>Various A-V sync and other audio problems</title> <sect2 id="bugs-delay-all"> -<title>General audio delay or jerky sound (exists with all or many files)</title> +<title>General audio delay or jerky sound + (exists with all or many files)</title> + <itemizedlist> <listitem><para> -most common: buggy audio driver! - try to use different drivers, try ALSA OSS -emulation with <option>-ao oss</option>, also try <option>-ao sdl</option>, -sometimes it helps. If your file plays fine with <option>-nosound</option>, then you can be sure -it's sound card (driver) problem. + most common: buggy audio driver! - try to use different drivers, try ALSA OSS + emulation with <option>-ao oss</option>, also try <option>-ao sdl</option>, + sometimes it helps. If your file plays fine with <option>-nosound</option>, + then you can be sure it's sound card (driver) problem. </para></listitem> <listitem> -<para>audio buffer problems (buffer size badly detected)</para> -<para>Workaround: <application>MPlayer</application>'s <option>-abs</option> option</para> + <para>audio buffer problems (buffer size badly detected)</para> + <para> + Workaround: <application>MPlayer</application>'s <option>-abs</option> option + </para> </listitem> <listitem><para> -samplerate problems - maybe your card doesn't support the samplerate used in your -files - try the resampling filter (<option>-af resample=...</option>) + samplerate problems - maybe your card doesn't support the samplerate used in + your files - try the resampling filter (<option>-af resample=...</option>) </para></listitem> <listitem> -<para>slow machine (CPU or VGA)</para> -<para>try with <option>-vo null</option>, if it plays well, then you have slow -VGA card/driver</para> -<para>Workaround: buy a faster card or read this documentation about how to -speed up</para> -<para>Also try <option>-framedrop</option></para> + <para>slow machine (CPU or VGA)</para> + <para> + try with <option>-vo null</option>, if it plays well, then you have slow + VGA card/driver + </para> + <para> + Workaround: buy a faster card or read this documentation about how to speed up + </para> + <para>Also try <option>-framedrop</option></para> </listitem> </itemizedlist> </sect2> +<!-- ********** --> <sect2 id="bugs-delay-specific"> <title>Audio delay/de-sync specific to one or a few files</title> + <itemizedlist> <listitem> -<para>bad file</para> -<para> -Workaround: + <para>bad file</para> + <para> + Workaround: <itemizedlist> <listitem> - <para><option>-ni</option> or <option>-nobps</option> option (for - non-interleaved or bad files)</para> + <para> + <option>-ni</option> or <option>-nobps</option> option + (for non-interleaved or bad files) + </para> <para>and/or</para> </listitem> <listitem> - <para><option>-mc 0</option> (required for files with badly - interleaved VBR audio)</para> + <para> + <option>-mc 0</option> + (required for files with badly interleaved VBR audio) + </para> <para>and/or</para> </listitem> <listitem> - <para><option>-delay</option> or <keycap>+</keycap>/<keycap>-</keycap> - keys at runtime to adjust delay</para> + <para> + <option>-delay</option> or <keycap>+</keycap>/<keycap>-</keycap> + keys at runtime to adjust delay + </para> </listitem> </itemizedlist> -If none of these help, please upload the file, we'll check (and fix). + If none of these help, please upload the file, we'll check (and fix). </para> </listitem> <listitem> -<para>your sound card doesn't support 48kHz playback</para> -<para>Workaround: buy a better sound card... or try to decrease fps by 10% (use -<option>-fps 27</option> for a 30fps movie) or use the resample filter</para> + <para>your sound card doesn't support 48kHz playback</para> + <para> + Workaround: buy a better sound card... or try to decrease fps by 10% + (use <option>-fps 27</option> for a 30fps movie) or use the resample filter + </para> </listitem> <listitem> -<para>slow machine (if A-V is not around 0, and the last number in the status -line increasing)</para> -<para>Workaround: <option>-framedrop</option></para> + <para> + slow machine (if A-V is not around 0, + and the last number in the status line increasing) + </para> + <para>Workaround: <option>-framedrop</option></para> </listitem> </itemizedlist> </sect2> +<!-- ********** --> <sect2 id="bugs-nosound"> <title>No sound at all</title> + <itemizedlist> <listitem> -<para>your file uses an unsupported audio codec</para> -<para>Solution: read the documentation and help us adding support for it</para> + <para>your file uses an unsupported audio codec</para> + <para> + Solution: read the documentation and help us adding support for it + </para> </listitem> </itemizedlist> </sect2> +<!-- ********** --> <sect2 id="bugs-nopicture"> <title>No picture at all (just plain grey/green window)</title> + <itemizedlist> <listitem> -<para>your file uses an unsupported video codec</para> -<para>Solution: read the documentation and help us adding support for it</para> + <para>your file uses an unsupported video codec</para> + <para> + Solution: read the documentation and help us adding support for it + </para> </listitem> <listitem> -<para> -auto-selected codec can't decode the file, try to select another using -<option>-vc</option> or <option>-vfm</option> options -</para> + <para> + auto-selected codec can't decode the file, try to select another using + <option>-vc</option> or <option>-vfm</option> options + </para> </listitem> </itemizedlist> </sect2> +<!-- ********** --> <sect2 id="bugs-video"> <title>Video-out problems</title> + <para> First note that the options <option>-fs</option>, <option>-vm</option> and <option>-zoom</option> are not supported by all drivers. Plus, not all @@ -154,18 +191,20 @@ <title>OSD/sub flickering</title> <para> <itemizedlist> -<listitem><para>x11 driver: sorry, it can't be fixed now</para></listitem> -<listitem><para>xv driver: use <option>-double</option> option</para></listitem> + <listitem><para>x11 driver: sorry, it can't be fixed now</para></listitem> + <listitem><para>xv driver: use <option>-double</option> option</para></listitem> </itemizedlist> </para> </formalpara> <formalpara> -<title>Green image using mga_vid (<option>-vo mga</option> / <option>-vo xmga</option>)</title> +<title>Green image using mga_vid + (<option>-vo mga</option> / <option>-vo xmga</option>)</title> <para> <itemizedlist> -<listitem><para>mga_vid misdetected your card's RAM amount, reload it using -<option>mga_ram_size</option> option +<listitem><para> + mga_vid misdetected your card's RAM amount, reload it using + <option>mga_ram_size</option> option. </para></listitem> </itemizedlist> </para>
--- a/DOCS/xml/en/cd-dvd.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/cd-dvd.xml Fri Dec 08 11:38:06 2006 +0000 @@ -14,16 +14,18 @@ <itemizedlist> <listitem><para> -There have been reports of read errors at high speeds, especially -with badly pressed CD-ROMs. Reducing the speed can prevent data loss under -these circumstances. + There have been reports of read errors at high speeds, especially + with badly pressed CD-ROMs. Reducing the speed can prevent data loss under + these circumstances. </para></listitem> <listitem><para> -Many CD-ROM drives are annoyingly loud, a lower speed may reduce the noise. + Many CD-ROM drives are annoyingly loud, a lower speed may reduce the noise. </para></listitem> </itemizedlist> +<!-- ********** --> + <sect2 id="drives_linux"> <title>Linux</title> @@ -49,28 +51,30 @@ This sets prefetched file reading to 2MB, which helps with scratched CD-ROMs. If you set it to too high, the drive will continuously spin up and down, and will dramatically decrease the performance. -It is recommended that you also tune your CD-ROM drive with <command>hdparm</command>: +It is recommended that you also tune your CD-ROM drive +with <command>hdparm</command>: <screen>hdparm -d1 -a8 -u1 <replaceable>[cdrom device]</replaceable></screen> </para> <para> -This enables DMA access, read-ahead, and IRQ unmasking (read the <command>hdparm</command> -man page for a detailed explanation). +This enables DMA access, read-ahead, and IRQ unmasking (read the +<command>hdparm</command> man page for a detailed explanation). </para> <para> -Please refer to "<filename>/proc/ide/<replaceable>[cdrom device]</replaceable>/settings</filename>" +Please refer to +"<filename>/proc/ide/<replaceable>[cdrom device]</replaceable>/settings</filename>" for fine-tuning your CD-ROM. </para> <para> -SCSI drives do not have a uniform way of setting these parameters (Do you know one? -Tell us!) There is a tool that works for +SCSI drives do not have a uniform way of setting these parameters (Do you know +one? Tell us!) There is a tool that works for <ulink url="http://das.ist.org/~georg/">Plextor SCSI drives</ulink>. </para> - </sect2> +<!-- ********** --> <sect2 id="drives_freebsd"> <title>FreeBSD</title> @@ -92,13 +96,18 @@ </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="dvd"> <title>DVD playback</title> + <para> For the complete list of available options, please read the man page. The syntax to play a standard DVD is as follows: -<screen>mplayer dvd://<replaceable><track></replaceable> [-dvd-device <replaceable><device></replaceable>]</screen> +<screen> +mplayer dvd://<replaceable><track></replaceable> [-dvd-device <replaceable><device></replaceable>] +</screen> </para> <para> @@ -200,12 +209,15 @@ </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="vcd"> <title>VCD playback</title> + <para> -For the complete list of available options, please read the man page. The Syntax for a -standard Video CD (VCD) is as follows: +For the complete list of available options, please read the man page. The +Syntax for a standard Video CD (VCD) is as follows: <screen>mplayer vcd://<replaceable><track></replaceable> [-cdrom-device <replaceable><device></replaceable>]</screen> Example: <screen>mplayer vcd://2 -cdrom-device /dev/hdc</screen> @@ -230,50 +242,50 @@ <formalpara> <title>VCD structure</title> - <para> A Video CD (VCD) is made up of CD-ROM XA sectors, i.e. CD-ROM mode 2 -form 1 and 2 tracks:</para> -</formalpara> - +form 1 and 2 tracks: <itemizedlist> <listitem><para> -The first track is in mode 2 form 2 format which means it uses L2 -error correction. The track contains an ISO-9660 filesystem with 2048 -bytes/sector. This filesystem contains VCD metadata information, as -well as still frames often used in menus. MPEG segments for menus can -also be stored in this first track, but the MPEGs have to be broken up -into a series of 150-sector chunks. The ISO-9660 filesystem may -contain other files or programs that are not essential for VCD -operation. + The first track is in mode 2 form 2 format which means it uses L2 + error correction. The track contains an ISO-9660 filesystem with 2048 + bytes/sector. This filesystem contains VCD metadata information, as + well as still frames often used in menus. MPEG segments for menus can + also be stored in this first track, but the MPEGs have to be broken up + into a series of 150-sector chunks. The ISO-9660 filesystem may + contain other files or programs that are not essential for VCD + operation. </para></listitem> <listitem><para> -The second and remaining tracks are generally raw 2324 bytes/sector -MPEG (movie) tracks, containing one MPEG PS data packet per -sector. These are in mode 2 form 1 format, so they store more data per -sector at the loss of some error correction. It is also legal to have -CD-DA tracks in a VCD after the first track as well. -On some operating systems there is some trickery that goes on to make -these non-ISO-9660 tracks appear in a filesystem. On other operating -systems like GNU/Linux this is not the case (yet). Here the MPEG data -<emphasis role="bold">cannot be mounted</emphasis>. As most movies are -inside this kind of track, you should try <option>vcd://2</option> -first.</para></listitem> + The second and remaining tracks are generally raw 2324 bytes/sector + MPEG (movie) tracks, containing one MPEG PS data packet per + sector. These are in mode 2 form 1 format, so they store more data per + sector at the loss of some error correction. It is also legal to have + CD-DA tracks in a VCD after the first track as well. + On some operating systems there is some trickery that goes on to make + these non-ISO-9660 tracks appear in a filesystem. On other operating + systems like GNU/Linux this is not the case (yet). Here the MPEG data + <emphasis role="bold">cannot be mounted</emphasis>. As most movies are + inside this kind of track, you should try <option>vcd://2</option> + first. +</para></listitem> <listitem><para> -There exist VCD disks without the first track (single track and no filesystem -at all). They are still playable, but cannot be mounted. + There exist VCD disks without the first track (single track and no filesystem + at all). They are still playable, but cannot be mounted. </para></listitem> -<listitem><para> The definition of the Video CD standard is called the -Philips "White Book" and it is not generally available online as it -must be purchased from Philips. More detailed information about Video -CDs can be found in the -<ulink url="http://www.vcdimager.org/pub/vcdimager/manuals/0.7/vcdimager.html#SEC4">vcdimager documentation</ulink>. +<listitem><para> + The definition of the Video CD standard is called the + Philips "White Book" and it is not generally available online as it + must be purchased from Philips. More detailed information about Video + CDs can be found in the + <ulink url="http://www.vcdimager.org/pub/vcdimager/manuals/0.7/vcdimager.html#SEC4">vcdimager documentation</ulink>. </para></listitem> - </itemizedlist> +</para> +</formalpara> <formalpara> <title>About .DAT files</title> @@ -287,12 +299,13 @@ be found in the Linux version of PowerDVD. It has a modified iso9660 filesystem (<filename>vcdfs/isofs-2.4.X.o</filename>) driver, which is able to emulate the raw tracks through this shadow .DAT file. If you mount the disc using their -driver, you can copy and even play .DAT files with <application>MPlayer</application>. But it will not +driver, you can copy and even play .DAT files with +<application>MPlayer</application>. But it will not work with the standard iso9660 driver of the Linux kernel! Use <option>vcd://</option> instead. Alternatives for VCD copying are the new <ulink url="http://www.elis.rug.ac.be/~ronsse/cdfs/">cdfs</ulink> kernel -driver (not part of the official kernel) that shows CD sessions as image files and -<ulink url="http://cdrdao.sf.net/">cdrdao</ulink>, a bit-by-bit +driver (not part of the official kernel) that shows CD sessions as image files +and <ulink url="http://cdrdao.sf.net/">cdrdao</ulink>, a bit-by-bit CD grabbing/copying application. </para> </formalpara>
--- a/DOCS/xml/en/codecs.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/codecs.xml Fri Dec 08 11:38:06 2006 +0000 @@ -22,52 +22,54 @@ <listitem><simpara> <emphasis role="bold">MPEG-1</emphasis> (<emphasis role="bold">VCD</emphasis>) and <emphasis role="bold">MPEG-2</emphasis> (<emphasis role="bold">DVD</emphasis>) video - </simpara></listitem> +</simpara></listitem> <listitem><simpara> native decoders for <emphasis role="bold">all DivX variants, 3ivX, M$ MPEG-4</emphasis> v1, v2 and other MPEG-4 variants - </simpara></listitem> +</simpara></listitem> <listitem><simpara> native decoder for <emphasis role="bold">Windows Media Video 7/8</emphasis> (<emphasis role="bold">WMV1/WMV2</emphasis>), and Win32 DLL decoder for <emphasis role="bold">Windows Media Video 9</emphasis> - (<emphasis role="bold">WMV3</emphasis>), both used in <filename>.wmv</filename> - files - </simpara></listitem> + (<emphasis role="bold">WMV3</emphasis>), + both used in <filename>.wmv</filename> files +</simpara></listitem> <listitem><simpara> native <emphasis role="bold">Sorenson 1 (SVQ1)</emphasis> decoder - </simpara></listitem> +</simpara></listitem> <listitem><simpara> native <emphasis role="bold">Sorenson 3 (SVQ3)</emphasis> decoder - </simpara></listitem> +</simpara></listitem> <listitem><simpara> <emphasis role="bold">3ivx</emphasis> v1, v2 decoder - </simpara></listitem> +</simpara></listitem> <listitem><simpara> - Cinepak and <emphasis role="bold">Intel Indeo</emphasis> codecs (3.1,3.2,4.1,5.0) - </simpara></listitem> + Cinepak and <emphasis role="bold">Intel Indeo</emphasis> codecs + (3.1,3.2,4.1,5.0) +</simpara></listitem> <listitem><simpara> <emphasis role="bold">MJPEG</emphasis>, AVID, VCR2, ASV2 and other hardware formats - </simpara></listitem> +</simpara></listitem> <listitem><simpara> - VIVO 1.0, 2.0, I263 and other <emphasis role="bold">H.263(+)</emphasis> variants - </simpara></listitem> + VIVO 1.0, 2.0, I263 and other <emphasis role="bold">H.263(+)</emphasis> + variants +</simpara></listitem> <listitem><simpara> FLI/FLC - </simpara></listitem> +</simpara></listitem> <listitem><simpara> <emphasis role="bold">RealVideo 1.0 & 2.0</emphasis> from <systemitem class="library">libavcodec</systemitem>, and - <emphasis role="bold">RealVideo 3.0 & 4.0</emphasis> codecs using RealPlayer - libraries - </simpara></listitem> + <emphasis role="bold">RealVideo 3.0 & 4.0</emphasis> codecs using + RealPlayer libraries +</simpara></listitem> <listitem><simpara> native decoder for HuffYUV - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Various old simple RLE-like formats - </simpara></listitem> +</simpara></listitem> </itemizedlist> <para> @@ -76,6 +78,7 @@ and help us add support for it. </para> +<!-- ********** --> <sect2 id="ffmpeg" xreflabel="FFmpeg/libavcodec"> <title>FFmpeg/libavcodec</title> @@ -104,9 +107,9 @@ <systemitem class="library">libavcodec</systemitem>. Just run <filename>./configure</filename> and compile. </para> - </sect2> +<!-- ********** --> <sect2 id="xvid"> <title>Xvid</title> @@ -118,6 +121,7 @@ It yields very good video quality and good performance due to CPU optimizations for most modern processors. </para> + <para> It began as a forked development of the OpenDivX codec. This happened when ProjectMayo changed OpenDivX to closed source @@ -146,179 +150,196 @@ </para> <step><para> <screen>cvs -z3 -d:pserver:anonymous@cvs.xvid.org:/xvid login</screen> - </para></step> +</para></step> <step><para> <screen>cvs -z3 -d:pserver:anonymous@cvs.xvid.org:/xvid co xvidcore</screen> </para></step> <step><para> <screen>cd xvidcore/build/generic</screen> - </para></step> +</para></step> <step><para> <screen>./bootstrap.sh</screen> - </para></step> +</para></step> <step><para> <screen>./configure</screen> You may have to add some options (examine the output of <command>./configure --help</command>). - </para></step> +</para></step> <step><para> <screen>make && make install</screen> - </para></step> +</para></step> <step><para> If you specified <option>--enable-divxcompat</option>, copy <filename>../../src/divx4.h</filename> to <filename class="directory">/usr/local/include/</filename>. - </para></step> +</para></step> <step><para> Recompile <application>MPlayer</application> with <option>--with-xvidlibdir=<replaceable>/path/to/</replaceable>libxvidcore.a</option> <option>--with-xvidincdir=<replaceable>/path/to/</replaceable>xvid.h</option>. - </para></step> +</para></step> </procedure> </sect2> +<!-- ********** --> <sect2 id="codec-x264"> <title><systemitem class="library">x264</systemitem></title> <sect3 id="codec-x264-whatis"> <title>What is <systemitem class="library">x264</systemitem>?</title> + <para> - <ulink url="http://developers.videolan.org/x264.html"><systemitem class="library">x264</systemitem></ulink> - is a library for - creating H.264 video streams. - It is not 100% complete, but currently it has at least some kind - of support for most of the H.264 features which impact quality. - There are also many advanced features in the H.264 specification - which have nothing to do with video quality per se; many of these - are not yet implemented in - <systemitem class="library">x264</systemitem>. +<ulink url="http://developers.videolan.org/x264.html"><systemitem class="library">x264</systemitem></ulink> +is a library for creating H.264 video streams. +It is not 100% complete, but currently it has at least some kind +of support for most of the H.264 features which impact quality. +There are also many advanced features in the H.264 specification +which have nothing to do with video quality per se; many of these +are not yet implemented in <systemitem class="library">x264</systemitem>. </para> <itemizedlist> <title>Encoder features</title> <listitem><para>CAVLC/CABAC</para></listitem> <listitem><para>Multi-references</para></listitem> - <listitem><para>Intra: all macroblock types (16x16, 8x8, and 4x4 with - all predictions)</para></listitem> - <listitem><para>Inter P: all partitions (from 16x16 down to - 4x4)</para></listitem> - <listitem><para>Inter B: partitions from 16x16 down to 8x8 - (including SKIP/DIRECT)</para></listitem> - <listitem><para>Ratecontrol: constant quantizer, constant bitrate, - single or multipass ABR, optional VBV</para></listitem> + <listitem><para> + Intra: all macroblock types (16x16, 8x8, and 4x4 with all predictions) + </para></listitem> + <listitem><para> + Inter P: all partitions (from 16x16 down to 4x4) + </para></listitem> + <listitem><para> + Inter B: partitions from 16x16 down to 8x8 (including SKIP/DIRECT) + </para></listitem> + <listitem><para> + Ratecontrol: constant quantizer, constant bitrate, single or multipass ABR, + optional VBV + </para></listitem> <listitem><para>Scene cut detection</para></listitem> <listitem><para>Adaptive B-frame placement</para></listitem> - <listitem><para>B-frames as references / arbitrary frame - order</para></listitem> + <listitem><para> + B-frames as references / arbitrary frame order + </para></listitem> <listitem><para>8x8 and 4x4 adaptive spatial transform</para></listitem> <listitem><para>Lossless mode</para></listitem> <listitem><para>Custom quantization matrices</para></listitem> <listitem><para>Parallel encoding of multiple slices</para></listitem> <listitem><para>Interlacing</para></listitem> </itemizedlist> +</sect3> -</sect3> <sect3 id="codec-h264-whatis"> <title>What is H.264?</title> + <para> - H.264 is one name for a new digital video codec jointly developed - by the ITU and MPEG. - It can also be correctly referred to by the cumbersome names of - "ISO/IEC 14496-10" or "MPEG-4 Part 10". - More frequently, it is referred to as "MPEG-4 AVC" or just "AVC". +H.264 is one name for a new digital video codec jointly developed +by the ITU and MPEG. +It can also be correctly referred to by the cumbersome names of +"ISO/IEC 14496-10" or "MPEG-4 Part 10". +More frequently, it is referred to as "MPEG-4 AVC" or just "AVC". </para> + <para> - Whatever you call it, H.264 may be worth trying because it can - typically match the quality of MPEG-4 ASP with 5%-30% less - bitrate. - Actual results will depend on both the source material and the - encoder. - The gains from using H.264 do not come for free: Decoding H.264 - streams seems to have steep CPU and memory requirements. - For instance, on a 1733 MHz Athlon, a DVD-resolution 1500kbps H.264 - video requires around 35% CPU to decode. - By comparison, decoding a DVD-resolution 1500kbps MPEG-4 ASP stream - requires around 10% CPU. - This means that decoding high-definition streams is almost out of - the question for most users. - It also means that even a decent DVD rip may sometimes stutter on - processors slower than 2.0 GHz or so. +Whatever you call it, H.264 may be worth trying because it can typically match +the quality of MPEG-4 ASP with 5%-30% less bitrate. +Actual results will depend on both the source material and the encoder. +The gains from using H.264 do not come for free: Decoding H.264 +streams seems to have steep CPU and memory requirements. +For instance, on a 1733 MHz Athlon, a DVD-resolution 1500kbps H.264 +video requires around 35% CPU to decode. +By comparison, decoding a DVD-resolution 1500kbps MPEG-4 ASP stream +requires around 10% CPU. +This means that decoding high-definition streams is almost out of +the question for most users. +It also means that even a decent DVD rip may sometimes stutter on +processors slower than 2.0 GHz or so. </para> + <para> - At least with <systemitem class="library">x264</systemitem>, - encoding requirements are not much worse than what you are used to - with MPEG-4 ASP. - For instance, on a 1733 MHz Athlon a typical DVD encode would run - at 5-15fps. +At least with <systemitem class="library">x264</systemitem>, +encoding requirements are not much worse than what you are used to +with MPEG-4 ASP. +For instance, on a 1733 MHz Athlon a typical DVD encode would run +at 5-15fps. </para> + <para> - This document is not intended to explain the details of H.264, - but if you are interested in a brief overview, you may want to read - <ulink url="http://www.cdt.luth.se/~peppar/kurs/smd151/spie04-h264OverviewPaper.pdf">The H.264/AVC Advanced Video Coding Standard: Overview and Introduction to the Fidelity Range Extensions</ulink>. +This document is not intended to explain the details of H.264, +but if you are interested in a brief overview, you may want to read +<ulink url="http://www.cdt.luth.se/~peppar/kurs/smd151/spie04-h264OverviewPaper.pdf">The H.264/AVC Advanced Video Coding Standard: Overview and Introduction to the Fidelity Range Extensions</ulink>. </para> </sect3> + <sect3 id="codec-x264-playback"> -<title>How can I play H.264 videos with <application>MPlayer</application>?</title> +<title>How can I play H.264 videos with + <application>MPlayer</application>?</title> + <para> - <application>MPlayer</application> uses - <systemitem class="library">libavcodec</systemitem>'s H.264 - decoder. - <systemitem class="library">libavcodec</systemitem> has had at - least minimally usable H.264 decoding since around July 2004, - however major changes and improvements have been implemented since - that time, both in terms of more functionalities supported and in - terms of improved CPU usage. - Just to be certain, it is always a good idea to use a recent Subversion - checkout. +<application>MPlayer</application> uses +<systemitem class="library">libavcodec</systemitem>'s H.264 decoder. +<systemitem class="library">libavcodec</systemitem> has had at +least minimally usable H.264 decoding since around July 2004, +however major changes and improvements have been implemented since +that time, both in terms of more functionalities supported and in +terms of improved CPU usage. +Just to be certain, it is always a good idea to use a recent Subversion +checkout. </para> + <para> - If you want a quick and easy way to know whether there have been - recent changes to <systemitem class="library">libavcodec</systemitem>'s - H.264 decoding, you might keep an eye on - <ulink url="http://svn.mplayerhq.hu/ffmpeg/trunk/libavcodec/h264.c?view=log">FFmpeg Subversion repository's web interface</ulink>. +If you want a quick and easy way to know whether there have been +recent changes to <systemitem class="library">libavcodec</systemitem>'s +H.264 decoding, you might keep an eye on +<ulink url="http://svn.mplayerhq.hu/ffmpeg/trunk/libavcodec/h264.c?view=log">FFmpeg Subversion repository's web interface</ulink>. </para> </sect3> + <sect3 id="codec-x264-encode"> -<title>How can I encode videos using <application>MEncoder</application> and <systemitem class="library">x264</systemitem>?</title> +<title>How can I encode videos using <application>MEncoder</application> + and <systemitem class="library">x264</systemitem>?</title> + <para> - If you have the subversion client installed, the latest x264 - sources can be gotten with this command: - <screen>svn co svn://svn.videolan.org/x264/trunk x264</screen> - <application>MPlayer</application> sources are updated whenever - an <systemitem class="library">x264</systemitem> API change - occurs, so it is always suggested to use - <application>MPlayer</application> from Subversion as well. - Perhaps this situation will change when and if an - <systemitem class="library">x264</systemitem> "release" occurs. - Meanwhile, <systemitem class="library">x264</systemitem> should - be considered very unstable, in the sense that its programming - interface is subject to change. +If you have the subversion client installed, the latest x264 +sources can be gotten with this command: +<screen>svn co svn://svn.videolan.org/x264/trunk x264</screen> +<application>MPlayer</application> sources are updated whenever +an <systemitem class="library">x264</systemitem> API change +occurs, so it is always suggested to use +<application>MPlayer</application> from Subversion as well. +Perhaps this situation will change when and if an +<systemitem class="library">x264</systemitem> "release" occurs. +Meanwhile, <systemitem class="library">x264</systemitem> should +be considered very unstable, in the sense that its programming +interface is subject to change. </para> + <para> - <systemitem class="library">x264</systemitem> is built and - installed in the standard way: - <screen>./configure && make && sudo make install</screen> - This installs libx264.a in /usr/local/lib and x264.h is placed in - /usr/local/include. +<systemitem class="library">x264</systemitem> is built and +installed in the standard way: +<screen>./configure && make && sudo make install</screen> +This installs libx264.a in /usr/local/lib and x264.h is placed in +/usr/local/include. - With the <systemitem class="library">x264</systemitem> library - and header placed in the standard locations, building - <application>MPlayer</application> with - <systemitem class="library">x264</systemitem> support is easy. - Just run the standard: - <screen>./configure && make && sudo make install</screen> - The <filename>./configure</filename> script will autodetect that you have satisfied the - requirements for <systemitem class="library">x264</systemitem>. +With the <systemitem class="library">x264</systemitem> library +and header placed in the standard locations, building +<application>MPlayer</application> with +<systemitem class="library">x264</systemitem> support is easy. +Just run the standard: +<screen>./configure && make && sudo make install</screen> +The <filename>./configure</filename> script will autodetect that you have +satisfied the requirements for <systemitem class="library">x264</systemitem>. </para> </sect3> </sect2> </sect1> -<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="audio-codecs"> <title>Audio codecs</title> @@ -328,48 +349,50 @@ <listitem><simpara> MPEG layer 1/2/3 (MP1/2/3) audio (<emphasis role="bold">native</emphasis> code, with MMX/SSE/3DNow! optimization) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> - Windows Media Audio 7 and 8 (AKA WMAv1 and WMAv2) (<emphasis role="bold">native</emphasis> code, with + Windows Media Audio 7 and 8 (AKA WMAv1 and WMAv2) + (<emphasis role="bold">native</emphasis> code, with <link linkend="ffmpeg"><systemitem class="library">libavcodec</systemitem></link>) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Windows Media Audio 9 (WMAv3) (using DMO DLL) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> AC3 Dolby audio (<emphasis role="bold">native</emphasis> code, with MMX/SSE/3DNow! optimization) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> AC3 passing through sound card hardware - </simpara></listitem> +</simpara></listitem> <listitem><simpara> AAC - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Ogg Vorbis audio codec (<emphasis role="bold">native</emphasis> library) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> RealAudio: DNET (low bitrate AC3), Cook, Sipro and ATRAC3 - </simpara></listitem> +</simpara></listitem> <listitem><simpara> QuickTime: Qualcomm and QDesign audio codecs - </simpara></listitem> +</simpara></listitem> <listitem><simpara> VIVO audio (g723, Vivo Siren) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Voxware audio (using DirectShow DLL) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> alaw and ulaw, various gsm, adpcm and pcm formats and other simple old audio codecs - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Adaptive Multi-Rate (AMR) speech codecs - </simpara></listitem> +</simpara></listitem> </itemizedlist> +<!-- ********** --> <sect2 id="swac3"> <title>Software AC3 decoding</title> @@ -391,9 +414,10 @@ channels. Use <option>-channels 2</option> for a stereo downmix. For a 4 channel downmix (Left Front, Right Front, Left Surround and Right Surround outputs), use <option>-channels 4</option>. In this case, any center -channel will be mixed equally to the front channels. <option>-channels -6</option> will output all the AC3 channels as they are encoded - in the -order Left, Right, Left Surround, Right Surround, Center and LFE. +channel will be mixed equally to the front channels. +<option>-channels 6</option> will output all the AC3 channels as they are +encoded - in the order Left, Right, Left Surround, Right Surround, Center and +LFE. </para> <para> @@ -409,9 +433,11 @@ </para> </sect2> +<!-- ********** --> <sect2 id="hwac3"> <title>Hardware AC3 decoding</title> + <para> You need an AC3 capable sound card, with digital out (S/PDIF). The card's driver must properly support the AFMT_AC3 format (C-Media does). Connect @@ -422,6 +448,7 @@ </para> </sect2> +<!-- ********** --> <sect2 id="libmad"> <title><systemitem class="library">libmad</systemitem> support</title> @@ -431,23 +458,27 @@ is a multiplatform, integer (internally 24bit PCM) only MPEG audio decoding library. It does not handle broken files well, and it sometimes has problems with seeking, but it may perform better on FPU-less -(such as <link linkend="arm">ARM</link>) platform than <systemitem class="library">mp3lib</systemitem>. +(such as <link linkend="arm">ARM</link>) +platform than <systemitem class="library">mp3lib</systemitem>. </para> <para> -If you have a proper installation of <systemitem class="library">libmad</systemitem>, -<filename>./configure</filename> -will notice and support for MPEG audio decoding via -<systemitem class="library">libmad</systemitem> will be built automatically. +If you have a proper installation of +<systemitem class="library">libmad</systemitem>, +<filename>./configure</filename> will notice and support for MPEG audio +decoding via <systemitem class="library">libmad</systemitem> will be built +automatically. </para> </sect2> +<!-- ********** --> + <sect2 id="hwmpa"> <title>Hardware MPEG audio codec</title> <para> -This codec (selected by <option>-ac hwmpa</option>) passes through MPEG audio packets -to hardware decoders, such as the ones found in full-featured DVB cards +This codec (selected by <option>-ac hwmpa</option>) passes through MPEG audio +packets to hardware decoders, such as the ones found in full-featured DVB cards and DXR2 adapters. Don't use it in combination with any other audio output device (such as OSS and ALSA) that isn't able to decode it (you will hear @@ -455,9 +486,11 @@ </para> </sect2> +<!-- ********** --> <sect2 id="aac"> <title>AAC codec</title> + <para> AAC (Advanced Audio Coding) is an audio codec sometimes found in MOV and MP4 files. An open source decoder called FAAD is available from @@ -470,7 +503,8 @@ If you use gcc 3.2 which fails to compile our internal FAAD or want to use the external library for some other reason, download the library from the <ulink url="http://www.audiocoding.com/modules/mydownloads/">download page</ulink> -and pass <option>--enable-faad-external</option> to <filename>./configure</filename>. +and pass <option>--enable-faad-external</option> +to <filename>./configure</filename>. You do not need all of faad2 to decode AAC files, libfaad is enough. Build it like this: <screen> @@ -482,14 +516,18 @@ make install </screen> Binaries are not available from audiocoding.com, but you can (apt-)get Debian -packages from <ulink url="http://www.debian-multimedia.org/">Christian Marillat's homepage</ulink>, -Mandrake/Mandriva RPMs from the <ulink url="http://plf.zarb.org">P.L.F</ulink> and RedHat RPMs -from <ulink url="http://greysector.rangers.eu.org/">Grey Sector</ulink>. +packages from +<ulink url="http://www.debian-multimedia.org/">Christian Marillat's homepage</ulink>, +Mandrake/Mandriva RPMs from the <ulink url="http://plf.zarb.org">P.L.F</ulink> +and RedHat RPMs from <ulink url="http://greysector.rangers.eu.org/">Grey Sector</ulink>. </para> </sect2> +<!-- ********** --> + <sect2 id="amr"> <title>AMR codecs</title> + <para> Adaptive Multi-Rate speech codec is used in third generation (3G) mobile phones. @@ -497,6 +535,7 @@ <ulink url="http://www.3gpp.org">The 3rd Generation Partnership Project</ulink> (free for private use). </para> + <para> To enable support, download the sources for <ulink url="http://www.3gpp.org/ftp/Specs/latest/Rel-6/26_series/26104-610.zip">AMR-NB</ulink> @@ -519,7 +558,9 @@ </sect1> -<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="codec-importing"> <title>Win32 codecs importing HOWTO</title> @@ -553,9 +594,7 @@ This is the MP3 codec. Now that you have all the necessary information (fourcc, codec file, sample AVI), submit your codec support request by mail, and upload these files to the FTP site: -<systemitem role="url"> -ftp://upload.mplayerhq.hu/MPlayer/incoming/<replaceable><codecname></replaceable>/ -</systemitem> +<systemitem role="url">ftp://upload.mplayerhq.hu/MPlayer/incoming/<replaceable><codecname></replaceable>/</systemitem> </para> <note><para>On Windows NT/2000/XP search for this info in the registry, @@ -564,6 +603,7 @@ </para></note> </sect2> +<!-- ********** --> <sect2 id="dshow-codecs"> <title>DirectShow codecs</title> @@ -575,10 +615,10 @@ <listitem><simpara> <filename>system.ini</filename> does not contain the needed information, instead it is stored in the registry and - </simpara></listitem> +</simpara></listitem> <listitem><simpara> we need the GUID of the codec. - </simpara></listitem> +</simpara></listitem> </itemizedlist> </para> @@ -590,37 +630,35 @@ <step><para> Get <application>GraphEdit</application> from either DirectX SDK or <ulink url="http://doom9.net">doom9</ulink>. - </para></step> +</para></step> <step><para> Start <command>graphedit.exe</command>. - </para></step> +</para></step> <step><para> From the menu select Graph -> Insert Filters. - </para></step> +</para></step> <step><para> Expand item <systemitem>DirectShow Filters</systemitem>. - </para></step> +</para></step> <step><para> Select the right codec name and expand item. - </para></step> +</para></step> <step><para> In the entry <systemitem>DisplayName</systemitem> look at the text in winged brackets after the backslash and write it down (five dash-delimited blocks, the GUID). - </para></step> +</para></step> <step><para> - The codec binary is the file specified in the <systemitem>Filename</systemitem> - entry. - </para></step> + The codec binary is the file specified in the + <systemitem>Filename</systemitem> entry. +</para></step> </procedure> -<note> -<para> +<note><para> If there is no <systemitem>Filename</systemitem> and <systemitem>DisplayName</systemitem> contains something like <systemitem>device:dmo</systemitem>, then it is a DMO-Codec. -</para> -</note> +</para></note> <procedure> <title>Old Method:</title> @@ -629,16 +667,16 @@ </para> <step><para> Start <command>regedit</command>. - </para></step> +</para></step> <step><para> Press <keycap>Ctrl</keycap>+<keycap>F</keycap>, disable the first two checkboxes, and enable the third. Type in the fourcc of the codec (e.g. <userinput>TM20</userinput>). - </para></step> +</para></step> <step><para> You should see a field which contains the path and the filename (e.g. <filename>C:\WINDOWS\SYSTEM\TM20DEC.AX</filename>). - </para></step> +</para></step> <step><para> Now that you have the file, we need the GUID. Try searching again, but now search for the codec's name, not the fourcc. Its name can be acquired @@ -646,28 +684,24 @@ <guimenu>File</guimenu> -> <guisubmenu>Properties</guisubmenu> -> <guimenuitem>Advanced</guimenuitem>. If not, you are out of luck. Try guessing (e.g. search for TrueMotion). - </para></step> +</para></step> <step><para> If the GUID is found you should see a <guilabel>FriendlyName</guilabel> and a <guilabel>CLSID</guilabel> field. Write down the 16 byte CLSID, this is the GUID we need. - </para></step> +</para></step> </procedure> -<note> -<para> +<note><para> If searching fails, try enabling all the checkboxes. You may have false hits, but you may get lucky... -</para> -</note> +</para></note> <para> Now that you have all the necessary information (fourcc, GUID, codec file, sample AVI), submit your codec support request by mail, and upload these files to the FTP site: -<systemitem -role="url">ftp://upload.mplayerhq.hu/MPlayer/incoming/<replaceable><codecname></replaceable>/ -</systemitem> +<systemitem role="url">ftp://upload.mplayerhq.hu/MPlayer/incoming/<replaceable><codecname></replaceable>/</systemitem> </para> <para>
--- a/DOCS/xml/en/containers.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/containers.xml Fri Dec 08 11:38:06 2006 +0000 @@ -15,7 +15,8 @@ <emphasis role="bold">container format</emphasis>. Examples of video <emphasis role="bold">codecs</emphasis> are: MPEG-1, MPEG-2, MPEG-4 (DivX), Indeo5, 3ivx. -Examples of container <emphasis role="bold">formats</emphasis> are: MPG, AVI, ASF. +Examples of container <emphasis role="bold">formats</emphasis> are: +MPG, AVI, ASF. </para> <para> @@ -26,10 +27,14 @@ does not have the necessary fields to describe its video and audio streams). Or you might put MPEG-1 video into an AVI file. <ulink url="http://ffmpeg.org/">FFmpeg</ulink> and -<link linkend="mencoder"><application>MEncoder</application></link> can create these files. +<link linkend="mencoder"><application>MEncoder</application></link> +can create these files. </para> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="video-formats"> <title>Video formats</title> @@ -45,21 +50,21 @@ MPG: This is the most <emphasis role="bold">basic</emphasis> form of the MPEG file formats. It contains MPEG-1 video, and MP2 (MPEG-1 layer 2) or rarely MP1 audio. - </simpara></listitem> +</simpara></listitem> <listitem><simpara> DAT: This is the very same format as MPG with a different extension. It is used on <emphasis role="bold">Video CDs</emphasis>. Due to the way VCDs are created and Linux is designed, the DAT files cannot be played nor copied from VCDs as regular files. You have to use <option>vcd://</option> to play a Video CD. - </simpara></listitem> +</simpara></listitem> <listitem><simpara> VOB: This is the MPEG file format on <emphasis role="bold">DVDs</emphasis>. It is the same as MPG, plus the capability to contain subtitles or non-MPEG (AC3) audio. It contains encoded MPEG-2 video and usually AC3 audio, but DTS, MP2 and uncompressed LPCM are allowed, too. <emphasis role="bold">Read the <link linkend="dvd">DVD</link> section</emphasis>! - </simpara></listitem> +</simpara></listitem> <listitem><simpara> TY: This is a TiVo MPEG stream. It contains MPEG PES data for audio and video streams, as well as extra information like closed captions. The @@ -67,7 +72,7 @@ TiVo. For more information on TiVo stream format, please refer to <ulink url="http://dvd-create.sourceforge.net/tystudio/tystream.shtml"> the TyStudio page</ulink>. - </simpara></listitem> +</simpara></listitem> </itemizedlist> <para> @@ -87,15 +92,18 @@ </para> </sect2> +<!-- ********** --> <sect2 id="avi"> <title>AVI files</title> <para> -Designed by Microsoft, <emphasis role="bold">AVI (Audio Video Interleaved)</emphasis> -is a widespread multipurpose format currently used mostly for MPEG-4 (DivX and DivX4) -video. It has many known drawbacks and shortcomings (for example in streaming). It -supports one video stream and 0 to 99 audio streams and can be as big as +Designed by Microsoft, +<emphasis role="bold">AVI (Audio Video Interleaved)</emphasis> +is a widespread multipurpose format currently used mostly for MPEG-4 (DivX and +DivX4) video. It has many known drawbacks and shortcomings (for example in +streaming). +It supports one video stream and 0 to 99 audio streams and can be as big as 2GB, but there exists an extension allowing bigger files called <emphasis role="bold">OpenDML</emphasis>. Microsoft currently strongly discourages its use and encourages ASF/WMV. Not that anybody cares. @@ -110,31 +118,30 @@ creating these files, <application>NanDub</application>, has this problem. </para> -<note> -<para> +<note><para> DV cameras create raw DV streams that DV grabbing utilities convert to two different types of AVI files. The AVI will then contain either separate audio and video streams that <application>MPlayer</application> can play or the raw DV stream for which support is under development. -</para> -</note> +</para></note> <para> There are two kinds of AVI files: <itemizedlist> <listitem><simpara> <emphasis role="bold">Interleaved:</emphasis> Audio and video content is - interleaved. This is the standard usage. Recommended and mostly used. Some tools - create interleaved AVIs with bad sync. <application>MPlayer</application> - detects these as interleaved, and this climaxes in loss of A/V sync, - probably at seeking. These files should be played as non-interleaved + interleaved. This is the standard usage. Recommended and mostly used. Some + tools create interleaved AVIs with bad sync. + <application>MPlayer</application> detects these as interleaved, and this + climaxes in loss of A/V sync, probably at seeking. + These files should be played as non-interleaved (with the <option>-ni</option> option). - </simpara></listitem> +</simpara></listitem> <listitem><simpara> <emphasis role="bold">Non-interleaved:</emphasis> First comes the whole video stream, then the whole audio stream. It thus needs a lot of seeking, making playing from network or CD-ROM difficult. - </simpara></listitem> +</simpara></listitem> </itemizedlist> </para> @@ -149,12 +156,13 @@ and <application>Windows Media Player</application>. Files with broken headers, and files created with VBR audio but not VBR-compliant encoder will result in A/V desync with this method (mostly at seeking). - </simpara></listitem> +</simpara></listitem> <listitem><simpara> - <emphasis role="bold">interleaving-based:</emphasis> It does not use the bitrate - value of the header, instead it uses the relative position of interleaved - audio and video chunks, making badly encoded files with VBR audio playable. - </simpara></listitem> + <emphasis role="bold">interleaving-based:</emphasis> It does not use the + bitrate value of the header, instead it uses the relative position of + interleaved audio and video chunks, + making badly encoded files with VBR audio playable. +</simpara></listitem> </itemizedlist> </para> @@ -169,13 +177,16 @@ </para> </sect2> +<!-- ********** --> <sect2 id="asf-wmv"> <title>ASF/WMV files</title> + <para> ASF (Active Streaming Format) comes from Microsoft. They developed two -variants of ASF, v1.0 and v2.0. v1.0 is used by their media tools (<application>Windows -Media Player</application> and <application>Windows Media Encoder</application>) +variants of ASF, v1.0 and v2.0. v1.0 is used by their media tools +(<application>Windows Media Player</application> and +<application>Windows Media Encoder</application>) and is very secret. v2.0 is published and patented :). Of course they differ, there is no compatibility at all (it is just another legal game). <application>MPlayer</application> supports only v1.0, as nobody has ever seen @@ -184,6 +195,7 @@ </para> </sect2> +<!-- ********** --> <sect2 id="mov"> <title>QuickTime/MOV files</title> @@ -194,12 +206,12 @@ extension. Note that since the MPEG-4 group chose QuickTime as the recommended file format for MPEG-4, their MOV files come with a <filename>.MPG</filename> or <filename>.MP4</filename> extension (Interestingly the video and audio -streams in these files are real MPG and AAC files. You can even extract them with the -<option>-dumpvideo</option> and <option>-dumpaudio</option> options.). +streams in these files are real MPG and AAC files. You can even extract them +with the <option>-dumpvideo</option> and <option>-dumpaudio</option> options.). </para> - </sect2> +<!-- ********** --> <sect2 id="vivo"> <title>VIVO files</title> @@ -212,21 +224,24 @@ </para> <para> -The video codec of VIVO/1.0 files is standard <emphasis role="bold">h.263</emphasis>. +The video codec of VIVO/1.0 files is standard +<emphasis role="bold">h.263</emphasis>. The video codec of VIVO/2.0 files is a modified, nonstandard <emphasis role="bold">h.263v2</emphasis>. The audio is the same, it may be <emphasis role="bold">g.723 (standard)</emphasis>, or <emphasis role="bold">Vivo Siren</emphasis>. </para> - </sect2> +<!-- ********** --> <sect2 id="fli"> <title>FLI files</title> + <para> <emphasis role="bold">FLI</emphasis> is a very old file format used by -Autodesk Animator, but it is a common file format for short animations on the net. +Autodesk Animator, but it is a common file format for short animations on the +net. <application>MPlayer</application> demuxes and decodes FLI movies and is even able to seek within them (useful when looping with the <option>-loop</option> option). FLI files do not have keyframes, so the @@ -234,6 +249,7 @@ </para> </sect2> +<!-- ********** --> <sect2 id="realmedia"> <title>RealMedia (RM) files</title> @@ -244,24 +260,29 @@ </para> </sect2> +<!-- ********** --> <sect2 id="nuppelvideo"> <title>NuppelVideo files</title> + <para> NuppelVideo is a TV grabber tool (AFAIK:). <application>MPlayer</application> can read its <filename>.NUV</filename> files (only NuppelVideo 5.0). Those files can contain uncompressed YV12, YV12+RTJpeg compressed, YV12 RTJpeg+lzo compressed, and YV12+lzo compressed frames. -<application>MPlayer</application> decodes (and also <emphasis role="bold">encodes</emphasis> +<application>MPlayer</application> decodes (and also +<emphasis role="bold">encodes</emphasis> them with <application>MEncoder</application> to MPEG-4 (DivX)/etc!) them all. Seeking works. </para> </sect2> +<!-- ********** --> <sect2 id="yuv4mpeg"> <title>yuv4mpeg files</title> + <para> <ulink url="http://mjpeg.sf.net">yuv4mpeg / yuv4mpeg2</ulink> is a file format used by the @@ -271,28 +292,35 @@ </para> </sect2> +<!-- ********** --> <sect2 id="film"> <title>FILM files</title> + <para> This format is used on old Sega Saturn CD-ROM games. </para> </sect2> +<!-- ********** --> <sect2 id="roq"> <title>RoQ files</title> + <para> RoQ files are multimedia files used in some ID games such as Quake III and Return to Castle Wolfenstein. </para> </sect2> +<!-- ********** --> <sect2 id="ogg"> <title>OGG/OGM files</title> + <para> -This is a new fileformat from <ulink url="http://www.xiph.org">Xiphophorus</ulink>. +This is a new fileformat from +<ulink url="http://www.xiph.org">Xiphophorus</ulink>. It can contain any video or audio codec, CBR or VBR. You'll need <systemitem class="library">libogg</systemitem> and <systemitem class="library">libvorbis</systemitem> installed before @@ -300,9 +328,11 @@ </para> </sect2> +<!-- ********** --> <sect2 id="sdp"> <title>SDP files</title> + <para> <ulink url="ftp://ftp.rfc-editor.org/in-notes/rfc2327.txt">SDP</ulink> is an IETF standard format for describing video and/or audio RTP streams. @@ -311,18 +341,23 @@ </para> </sect2> +<!-- ********** --> <sect2 id="pva"> <title>PVA files</title> + <para> PVA is an MPEG-like format used by DVB TV boards' software (e.g.: -<application>MultiDec</application>, <application>WinTV</application> under Windows). +<application>MultiDec</application>, +<application>WinTV</application> under Windows). </para> </sect2> +<!-- ********** --> <sect2 id="nsv"> <title>NSV files</title> + <para> NSV (NullSoft Video) is the file format used by the <application>Winamp</application> player to stream audio and video. @@ -337,18 +372,22 @@ </para> </sect2> +<!-- ********** --> <sect2 id="matroska"> <title>Matroska files</title> + <para> Matroska is an open container format. Read more on the <ulink url="http://www.matroska.org/">official site</ulink>. </para> </sect2> +<!-- ********** --> <sect2 id="nut"> <title>NUT files</title> + <para> NUT is the container format developed by <application>MPlayer</application> and <application>FFmpeg</application> folks. Both projects support it. @@ -356,17 +395,20 @@ </para> </sect2> +<!-- ********** --> <sect2 id="gif"> <title>GIF files</title> + <para> The <emphasis role="bold">GIF</emphasis> format is a common format for web -graphics. There are two versions of the GIF spec, GIF87a and GIF89a. The -main difference is that GIF89a allows for animation. <application>MPlayer</application> -supports both formats through use of <systemitem class="library">libungif</systemitem> or +graphics. There are two versions of the GIF spec, GIF87a and GIF89a. +The main difference is that GIF89a allows for animation. +<application>MPlayer</application> supports both formats through use of +<systemitem class="library">libungif</systemitem> or another libgif-compatible library. Non-animated GIFs will be displayed as -single frame videos. (Use the <option>-loop</option> and <option>-fixed-vo</option> -options to display these longer.) +single frame videos. (Use the <option>-loop</option> and +<option>-fixed-vo</option> options to display these longer.) </para> <para> @@ -385,8 +427,8 @@ </para> <para> -If your distribution does not come with <systemitem class="library">libungif</systemitem>, -download a copy from the +If your distribution does not come with +<systemitem class="library">libungif</systemitem>, download a copy from the <ulink url="http://sourceforge.net/projects/libungif">libungif homepage</ulink>. For detailed technical information, have a look at the <ulink url="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">GIF89a specification</ulink>. @@ -394,7 +436,9 @@ </sect2> </sect1> -<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="audio-formats"> <title>Audio formats</title> @@ -407,8 +451,11 @@ url="http://www.xmms.org">XMMS</ulink>. </para> +<!-- ********** --> + <sect2 id="mp3"> <title>MP3 files</title> + <para> You may have problems playing certain MP3 files that <application>MPlayer</application> will misdetect as MPEGs and play @@ -419,8 +466,11 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="ogg-vorbis"> <title>OGG/OGM files (Vorbis)</title> + <para> Requires properly installed <systemitem class="library">libogg</systemitem> and @@ -428,8 +478,11 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="cdda"> <title>CD audio</title> + <para> <application>MPlayer</application> can use <application>cdparanoia</application> to play CDDA (Audio CD). The scope of this section does not contain enumerating @@ -442,9 +495,12 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="xmms"> <title>XMMS</title> <para> + <application>MPlayer</application> can use <application>XMMS</application> input plugins to play many file formats. There are plugins for SNES game tunes, SID tunes (from Commodore 64), many Amiga formats, .xm, .it, VQF, musepack, Bonk, @@ -454,10 +510,12 @@ <para> For this feature you need to have <application>XMMS</application> and compile -<application>MPlayer</application> with <filename>./configure --enable-xmms</filename>. +<application>MPlayer</application> with +<filename>./configure --enable-xmms</filename>. If that does not work, you might need to set the <application>XMMS</application> -plugin and library path explicitly by way of the <option>--with-xmmsplugindir</option> -and <option>--with-xmmslibdir</option> options. +plugin and library path explicitly by way of the +<option>--with-xmmsplugindir</option> and <option>--with-xmmslibdir</option> +options. </para> </sect2> </sect1>
--- a/DOCS/xml/en/documentation.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/documentation.xml Fri Dec 08 11:38:06 2006 +0000 @@ -62,11 +62,12 @@ <para> <application>MPlayer</application> is a movie player for Linux (runs on many other Unices, and <emphasis role="bold">non-x86</emphasis> CPUs, see -<xref linkend="ports"/>). It plays most MPEG, VOB, AVI, OGG/OGM, VIVO, ASF/WMA/WMV, -QT/MOV/MP4, FLI, RM, NuppelVideo, yuv4mpeg, FILM, RoQ, PVA, Matroska files, supported by +<xref linkend="ports"/>). +It plays most MPEG, VOB, AVI, OGG/OGM, VIVO, ASF/WMA/WMV, QT/MOV/MP4, FLI, RM, +NuppelVideo, yuv4mpeg, FILM, RoQ, PVA, Matroska files, supported by many native, XAnim, RealPlayer, and Win32 DLL codecs. You can watch -<emphasis role="bold">VideoCD, SVCD, DVD, 3ivx, RealMedia, Sorenson, Theora</emphasis>, and -<emphasis role="bold">MPEG-4 (DivX)</emphasis> movies too. Another big +<emphasis role="bold">VideoCD, SVCD, DVD, 3ivx, RealMedia, Sorenson, Theora</emphasis>, +and <emphasis role="bold">MPEG-4 (DivX)</emphasis> movies too. Another big feature of <application>MPlayer</application> is the wide range of supported output drivers. It works with X11, Xv, DGA, OpenGL, SVGAlib, fbdev, AAlib, libcaca, DirectFB, but you can use GGI and SDL (and this way all @@ -76,7 +77,8 @@ <application>MPlayer</application> supports displaying through some hardware MPEG decoder boards, such as the <link linkend="dvb">DVB</link> and <link linkend="dxr3">DXR3/Hollywood+</link>. And what about the nice big -antialiased shaded subtitles (<emphasis role="bold">14 supported types</emphasis>) +antialiased shaded subtitles +(<emphasis role="bold">14 supported types</emphasis>) with European/ISO 8859-1,2 (Hungarian, English, Czech, etc), Cyrillic, Korean fonts, and the onscreen display (OSD)? </para> @@ -97,67 +99,67 @@ Encoder) is a simple movie encoder, designed to encode <application>MPlayer</application>-playable movies (<emphasis role="bold">AVI/ASF/OGG/DVD/VCD/VOB/MPG/MOV/VIV/FLI/RM/NUV/NET/PVA</emphasis>) -to other <application>MPlayer</application>-playable formats (see below). It -can encode with various codecs, like <emphasis role="bold">MPEG-4 (DivX4)</emphasis> +to other <application>MPlayer</application>-playable formats (see below). +It can encode with various codecs, like +<emphasis role="bold">MPEG-4 (DivX4)</emphasis> (one or two passes), <systemitem class="library">libavcodec</systemitem>, <emphasis role="bold">PCM/MP3/VBR MP3</emphasis> audio. </para> - <itemizedlist> <title><application>MEncoder</application> features</title> <listitem><simpara> Encoding from the wide range of fileformats and decoders of <application>MPlayer</application> - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Encoding to all the codecs of FFmpeg's <link linkend="ffmpeg"><systemitem class="library">libavcodec</systemitem></link> - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Video encoding from <emphasis role="bold">V4L compatible TV tuners</emphasis> - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Encoding/multiplexing to interleaved AVI files with proper index - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Creating files from external audio stream - </simpara></listitem> +</simpara></listitem> <listitem><simpara> 1, 2 or 3 pass encoding - </simpara></listitem> +</simpara></listitem> <listitem><para> <emphasis role="bold">VBR</emphasis> MP3 audio <important><simpara> VBR MP3 audio doesn't always play nicely on windows players! </simpara></important> - </para></listitem> +</para></listitem> <listitem><simpara> PCM audio - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Stream copying - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Input A/V synchronizing (PTS-based, can be disabled with <option>-mc 0</option> option) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> fps correction with <option>-ofps</option> option (useful when encoding 30000/1001 fps VOB to 24000/1001 fps AVI) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Using our very powerful filter system (crop, expand, flip, postprocess, rotate, scale, rgb/yuv conversion) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Can encode DVD/VOBsub <emphasis role="bold">AND</emphasis> text subtitles into the output file - </simpara></listitem> +</simpara></listitem> <listitem><simpara> Can rip DVD subtitles to VOBsub format - </simpara></listitem> +</simpara></listitem> </itemizedlist> <itemizedlist> @@ -165,7 +167,7 @@ <listitem><simpara> Even wider variety of available en/decoding formats/codecs (creating VOB files with DivX4/Indeo5/VIVO streams :). - </simpara></listitem> +</simpara></listitem> </itemizedlist> <!-- FIXME: the license should be in bookinfo -->
--- a/DOCS/xml/en/encoding-guide.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/encoding-guide.xml Fri Dec 08 11:38:06 2006 +0000 @@ -4,82 +4,90 @@ <title>Encoding with <application>MEncoder</application></title> <sect1 id="menc-feat-dvd-mpeg4"> -<title>Making a high quality MPEG-4 ("DivX") rip of a DVD movie</title> - -<para> - One frequently asked question is "How do I make the highest quality rip for - a given size?". Another question is "How do I make the highest quality DVD - rip possible? I do not care about file size, I just want the best quality." -</para> - -<para> - The latter question is perhaps at least somewhat wrongly posed. After all, if - you do not care about file size, why not simply copy the entire MPEG-2 video - stream from the the DVD? Sure, your AVI will end up being 5GB, give - or take, but if you want the best quality and do not care about size, - this is certainly your best option. -</para> - -<para> - In fact, the reason you want to transcode a DVD into MPEG-4 is - specifically because you <emphasis role="bold">do</emphasis> care about - file size. -</para> - -<para> - It is difficult to offer a cookbook recipe on how to create a very high - quality DVD rip. There are several factors to consider, and you should - understand these details or else you are likely to end up disappointed - with your results. Below we will investigate some of these issues, and - then have a look at an example. We assume you are using - <systemitem class="library">libavcodec</systemitem> to encode the video, - although the theory applies to other codecs as well. -</para> - -<para> - If this seems to be too much for you, you should probably use one of the - many fine frontends that are listed in the - <ulink url="http://www.mplayerhq.hu/design7/projects.html#mencoder_frontends">MEncoder section</ulink> - of our related projects page. - That way, you should be able to achieve high quality rips without too much - thinking, because most of those tools are designed to take clever decisions - for you. -</para> +<title>Making a high quality MPEG-4 ("DivX") + rip of a DVD movie</title> + +<para> +One frequently asked question is "How do I make the highest quality rip +for a given size?". Another question is "How do I make the highest +quality DVD rip possible? I do not care about file size, I just want the best +quality." +</para> + +<para> +The latter question is perhaps at least somewhat wrongly posed. After all, if +you do not care about file size, why not simply copy the entire MPEG-2 video +stream from the the DVD? Sure, your AVI will end up being 5GB, give +or take, but if you want the best quality and do not care about size, +this is certainly your best option. +</para> + +<para> +In fact, the reason you want to transcode a DVD into MPEG-4 is +specifically because you <emphasis role="bold">do</emphasis> care about +file size. +</para> + +<para> +It is difficult to offer a cookbook recipe on how to create a very high +quality DVD rip. There are several factors to consider, and you should +understand these details or else you are likely to end up disappointed +with your results. Below we will investigate some of these issues, and +then have a look at an example. We assume you are using +<systemitem class="library">libavcodec</systemitem> to encode the video, +although the theory applies to other codecs as well. +</para> + +<para> +If this seems to be too much for you, you should probably use one of the +many fine frontends that are listed in the +<ulink url="http://www.mplayerhq.hu/design7/projects.html#mencoder_frontends">MEncoder section</ulink> +of our related projects page. +That way, you should be able to achieve high quality rips without too much +thinking, because most of those tools are designed to take clever decisions +for you. +</para> + +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-preparing-encode"> <title>Preparing to encode: Identifying source material and framerate</title> -<para> - Before you even think about encoding a movie, you need to take - several preliminary steps. -</para> - -<para> - The first and most important step before you encode should be - determining what type of content you are dealing with. - If your source material comes from DVD or broadcast/cable/satellite - TV, it will be stored in one of two formats: NTSC for North - America and Japan, PAL for Europe, etc. - It is important to realize, however, that this is just the formatting for - presentation on a television, and often does - <emphasis role="bold">not</emphasis> correspond to the - original format of the movie. - Experience shows that NTSC material is a lot more difficult to encode, - because there more elements to identify in the source. - In order to produce a suitable encode, you need to know the original - format. - Failure to take this into account will result in various flaws in your - encode, including ugly combing (interlacing) artifacts and duplicated - or even lost frames. - Besides being ugly, the artifacts also harm coding efficiency: - You will get worse quality per unit bitrate. -</para> + +<para> +Before you even think about encoding a movie, you need to take +several preliminary steps. +</para> + +<para> +The first and most important step before you encode should be +determining what type of content you are dealing with. +If your source material comes from DVD or broadcast/cable/satellite +TV, it will be stored in one of two formats: NTSC for North +America and Japan, PAL for Europe, etc. +It is important to realize, however, that this is just the formatting for +presentation on a television, and often does +<emphasis role="bold">not</emphasis> correspond to the +original format of the movie. +Experience shows that NTSC material is a lot more difficult to encode, +because there more elements to identify in the source. +In order to produce a suitable encode, you need to know the original +format. +Failure to take this into account will result in various flaws in your +encode, including ugly combing (interlacing) artifacts and duplicated +or even lost frames. +Besides being ugly, the artifacts also harm coding efficiency: +You will get worse quality per unit bitrate. +</para> + <sect3 id="menc-feat-dvd-mpeg4-preparing-encode-fps"> <title>Identifying source framerate</title> -<para> - Here is a list of common types of source material, where you are - likely to find them, and their properties: -</para> + +<para> +Here is a list of common types of source material, where you are +likely to find them, and their properties: +</para> + <itemizedlist> <listitem><para> <emphasis role="bold">Standard Film</emphasis>: Produced for @@ -122,31 +130,35 @@ </itemizedlist> </sect3> + <sect3 id="menc-feat-dvd-mpeg4-preparing-encode-material"> <title>Identifying source material</title> -<para> - Movies consisting of frames are referred to as progressive, - while those consisting of independent fields are called - either interlaced or video - though this latter term is - ambiguous. -</para> -<para> - To further complicate matters, some movies will be a mix of - several of the above. -</para> -<para> - The most important distinction to make between all of these - formats is that some are frame-based, while others are - field-based. - <emphasis role="bold">Whenever</emphasis> a movie is prepared - for display on television (including DVD), it is converted to a - field-based format. - The various methods by which this can be done are collectively - referred to as "telecine", of which the infamous NTSC - "3:2 pulldown" is one variety. - Unless the original material was also field-based (and the same - fieldrate), you are getting the movie in a format other than the - original. + +<para> +Movies consisting of frames are referred to as progressive, +while those consisting of independent fields are called +either interlaced or video - though this latter term is +ambiguous. +</para> + +<para> +To further complicate matters, some movies will be a mix of +several of the above. +</para> + +<para> +The most important distinction to make between all of these +formats is that some are frame-based, while others are +field-based. +<emphasis role="bold">Whenever</emphasis> a movie is prepared +for display on television (including DVD), it is converted to a +field-based format. +The various methods by which this can be done are collectively +referred to as "telecine", of which the infamous NTSC +"3:2 pulldown" is one variety. +Unless the original material was also field-based (and the same +fieldrate), you are getting the movie in a format other than the +original. </para> <itemizedlist> @@ -183,39 +195,41 @@ </itemizedlist> <para> - There are also methods for converting between NTSC and PAL video, - but such topics are beyond the scope of this guide. - If you encounter such a movie and want to encode it, your best - bet is to find a copy in the original format. - Conversion between these two formats is highly destructive and - cannot be reversed cleanly, so your encode will greatly suffer - if it is made from a converted source. -</para> -<para> - When video is stored on DVD, consecutive pairs of fields are - grouped as a frame, even though they are not intended to be shown - at the same moment in time. - The MPEG-2 standard used on DVD and digital TV provides a - way both to encode the original progressive frames and to store - the number of fields for which a frame should be shown in the - header of that frame. - If this method has been used, the movie will often be described - as "soft-telecined", since the process only directs the - DVD player to apply pulldown to the movie rather than altering - the movie itself. - This case is highly preferable since it can easily be reversed - (actually ignored) by the encoder, and since it preserves maximal - quality. - However, many DVD and broadcast production studios do not use - proper encoding techniques but instead produce movies with - "hard telecine", where fields are actually duplicated in the - encoded MPEG-2. -</para> -<para> - The procedures for dealing with these cases will be covered - <link linkend="menc-feat-telecine">later in this guide</link>. - For now, we leave you with some guides to identifying which type - of material you are dealing with: +There are also methods for converting between NTSC and PAL video, +but such topics are beyond the scope of this guide. +If you encounter such a movie and want to encode it, your best +bet is to find a copy in the original format. +Conversion between these two formats is highly destructive and +cannot be reversed cleanly, so your encode will greatly suffer +if it is made from a converted source. +</para> + +<para> +When video is stored on DVD, consecutive pairs of fields are +grouped as a frame, even though they are not intended to be shown +at the same moment in time. +The MPEG-2 standard used on DVD and digital TV provides a +way both to encode the original progressive frames and to store +the number of fields for which a frame should be shown in the +header of that frame. +If this method has been used, the movie will often be described +as "soft-telecined", since the process only directs the +DVD player to apply pulldown to the movie rather than altering +the movie itself. +This case is highly preferable since it can easily be reversed +(actually ignored) by the encoder, and since it preserves maximal +quality. +However, many DVD and broadcast production studios do not use +proper encoding techniques but instead produce movies with +"hard telecine", where fields are actually duplicated in the +encoded MPEG-2. +</para> + +<para> +The procedures for dealing with these cases will be covered +<link linkend="menc-feat-telecine">later in this guide</link>. +For now, we leave you with some guides to identifying which type +of material you are dealing with: </para> <itemizedlist> @@ -232,9 +246,9 @@ "combing" at times, then there are several possibilities. The 24000/1001 fps segments are almost certainly progressive content, "soft telecined", but the 30000/1001 fps parts could be - either hard-telecined 24000/1001 fps content or 60000/1001 fields per second NTSC video. - Use the same guidelines as the following two cases to determine - which. + either hard-telecined 24000/1001 fps content or 60000/1001 fields per second + NTSC video. + Use the same guidelines as the following two cases to determine which. </para></listitem> <listitem><para> If <application>MPlayer</application> never shows the framerate @@ -268,192 +282,194 @@ <application>MPlayer</application> can slow down movie playback with the -speed option or play it frame-by-frame. Try using <option>-speed</option> 0.2 to watch the movie very - slowly or press the "<keycap>.</keycap>" key repeatedly to play one frame at a time - and identify the pattern, if you cannot see it at full speed. + slowly or press the "<keycap>.</keycap>" key repeatedly to play one frame at + a time and identify the pattern, if you cannot see it at full speed. </para> </note> </sect3> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-dvd-mpeg4-2pass"> <title>Constant quantizer vs. multipass</title> <para> - It is possible to encode your movie at a wide range of qualities. - With modern video encoders and a bit of pre-codec compression - (downscaling and denoising), it is possible to achieve very good - quality at 700 MB, for a 90-110 minute widescreen movie. - Furthermore, all but the longest movies can be encoded with near-perfect - quality at 1400 MB. -</para> - -<para> - There are three approaches to encoding the video: constant bitrate - (CBR), constant quantizer, and multipass (ABR, or average bitrate). -</para> - -<para> - The complexity of the frames of a movie, and thus the number of bits - required to compress them, can vary greatly from one scene to another. - Modern video encoders can adjust to these needs as they go and vary - the bitrate. - In simple modes such as CBR, however, the encoders do not know the - bitrate needs of future scenes and so cannot exceed the requested - average bitrate for long stretches of time. - More advanced modes, such as multipass encode, can take into account - the statistics from previous passes; this fixes the problem mentioned - above. +It is possible to encode your movie at a wide range of qualities. +With modern video encoders and a bit of pre-codec compression +(downscaling and denoising), it is possible to achieve very good +quality at 700 MB, for a 90-110 minute widescreen movie. +Furthermore, all but the longest movies can be encoded with near-perfect +quality at 1400 MB. +</para> + +<para> +There are three approaches to encoding the video: constant bitrate +(CBR), constant quantizer, and multipass (ABR, or average bitrate). +</para> + +<para> +The complexity of the frames of a movie, and thus the number of bits +required to compress them, can vary greatly from one scene to another. +Modern video encoders can adjust to these needs as they go and vary +the bitrate. +In simple modes such as CBR, however, the encoders do not know the +bitrate needs of future scenes and so cannot exceed the requested +average bitrate for long stretches of time. +More advanced modes, such as multipass encode, can take into account +the statistics from previous passes; this fixes the problem mentioned +above. </para> <note><title>Note:</title> <para> - Most codecs which support ABR encode only support two pass encode - while some others such as <systemitem class="library">x264</systemitem>, - <systemitem class="library">Xvid</systemitem> - and <systemitem class="library">libavcodec</systemitem> support - multipass, which slightly improves quality at each pass, - yet this improvement is no longer measurable nor noticeable after the - 4th or so pass. - Therefore, in this section, two pass and multipass will be used - interchangeably. +Most codecs which support ABR encode only support two pass encode +while some others such as <systemitem class="library">x264</systemitem>, +<systemitem class="library">Xvid</systemitem> +and <systemitem class="library">libavcodec</systemitem> support +multipass, which slightly improves quality at each pass, +yet this improvement is no longer measurable nor noticeable after the +4th or so pass. +Therefore, in this section, two pass and multipass will be used +interchangeably. </para> </note> <para> - In each of these modes, the video codec (such as - <systemitem class="library">libavcodec</systemitem>) - breaks the video frame into 16x16 pixel macroblocks and then applies a - quantizer to each macroblock. The lower the quantizer, the better the - quality and higher the bitrate. - The method the movie encoder uses to determine - which quantizer to use for a given macroblock varies and is highly - tunable. (This is an extreme over-simplification of the actual - process, but the basic concept is useful to understand.) -</para> - -<para> - When you specify a constant bitrate, the video codec will encode the video, - discarding - detail as much as necessary and as little as possible in order to remain - lower than the given bitrate. If you truly do not care about file size, - you could as well use CBR and specify a bitrate of infinity. (In - practice, this means a value high enough so that it poses no limit, like - 10000Kbit.) With no real restriction on bitrate, the result is that - the codec will use the lowest - possible quantizer for each macroblock (as specified by - <option>vqmin</option> for - <systemitem class="library">libavcodec</systemitem>, which is 2 by default). - As soon as you specify a - low enough bitrate that the codec - is forced to use a higher quantizer, then you are almost certainly ruining - the quality of your video. - In order to avoid that, you should probably downscale your video, according - to the method described later on in this guide. - In general, you should avoid CBR altogether if you care about quality. -</para> - -<para> - With constant quantizer, the codec uses the same quantizer, as - specified by the <option>vqscale</option> option (for - <systemitem class="library">libavcodec</systemitem>), on every macroblock. - If you want the highest quality rip possible, again ignoring bitrate, - you can use <option>vqscale=2</option>. - This will yield the same bitrate and PSNR (peak signal-to-noise ratio) - as CBR with - <option>vbitrate</option>=infinity and the default <option>vqmin</option> - of 2. -</para> - -<para> - The problem with constant quantizing is that it uses the given quantizer - whether the macroblock needs it or not. That is, it might be possible - to use a higher quantizer on a macroblock without sacrificing visual - quality. Why waste the bits on an unnecessarily low quantizer? Your - CPU has as many cycles as there is time, but there is only so many bits - on your hard disk. -</para> - -<para> - With a two pass encode, the first pass will rip the movie as though it - were CBR, but it will keep a log of properties for each frame. This - data is then used during the second pass in order to make intelligent - decisions about which quantizers to use. During fast action or high - detail scenes, higher quantizers will likely be used, and during - slow moving or low detail scenes, lower quantizers will be used. - Normally, the amount of motion is much more important than the - amount of detail. -</para> - -<para> - If you use <option>vqscale=2</option>, then you are wasting bits. If you - use <option>vqscale=3</option>, then you are not getting the highest - quality rip. Suppose you rip a DVD at <option>vqscale=3</option>, and - the result is 1800Kbit. If you do a two pass encode with - <option>vbitrate=1800</option>, the resulting video will have <emphasis - role="bold">higher quality</emphasis> for the - <emphasis role="bold">same bitrate</emphasis>. -</para> - -<para> - Since you are now convinced that two pass is the way to go, the real - question now is what bitrate to use? The answer is that there is no - single answer. Ideally you want to choose a bitrate that yields the - best balance between quality and file size. This is going to vary - depending on the source video. -</para> - -<para> - If size does not matter, a good starting point for a very high quality - rip is about 2000Kbit plus or minus 200Kbit. - For fast action or high detail source video, or if you just have a very - critical eye, you might decide on 2400 or 2600. - For some DVDs, you might not notice a difference at 1400Kbit. It is a - good idea to experiment with scenes at different bitrates to get a feel. -</para> - -<para> - If you aim at a certain size, you will have to somehow calculate the bitrate. - But before that, you need to know how much space you should reserve for the - audio track(s), so you should <link linkend="menc-feat-dvd-mpeg4-audio">rip - those</link> first. - You can compute the bitrate with the following equation: - <systemitem>bitrate = (target_size_in_Mbytes - sound_size_in_Mbytes) * - 1024 * 1024 / length_in_secs * 8 / 1000</systemitem> - For instance, to squeeze a two-hour movie onto a 702MB CD, with 60MB - of audio track, the video bitrate will have to be: - <systemitem>(702 - 60) * 1024 * 1024 / (120*60) * 8 / 1000 - = 740kbps</systemitem> -</para> - +In each of these modes, the video codec (such as +<systemitem class="library">libavcodec</systemitem>) +breaks the video frame into 16x16 pixel macroblocks and then applies a +quantizer to each macroblock. The lower the quantizer, the better the +quality and higher the bitrate. +The method the movie encoder uses to determine +which quantizer to use for a given macroblock varies and is highly +tunable. (This is an extreme over-simplification of the actual +process, but the basic concept is useful to understand.) +</para> + +<para> +When you specify a constant bitrate, the video codec will encode the video, +discarding +detail as much as necessary and as little as possible in order to remain +lower than the given bitrate. If you truly do not care about file size, +you could as well use CBR and specify a bitrate of infinity. (In +practice, this means a value high enough so that it poses no limit, like +10000Kbit.) With no real restriction on bitrate, the result is that +the codec will use the lowest +possible quantizer for each macroblock (as specified by +<option>vqmin</option> for +<systemitem class="library">libavcodec</systemitem>, which is 2 by default). +As soon as you specify a +low enough bitrate that the codec +is forced to use a higher quantizer, then you are almost certainly ruining +the quality of your video. +In order to avoid that, you should probably downscale your video, according +to the method described later on in this guide. +In general, you should avoid CBR altogether if you care about quality. +</para> + +<para> +With constant quantizer, the codec uses the same quantizer, as +specified by the <option>vqscale</option> option (for +<systemitem class="library">libavcodec</systemitem>), on every macroblock. +If you want the highest quality rip possible, again ignoring bitrate, +you can use <option>vqscale=2</option>. +This will yield the same bitrate and PSNR (peak signal-to-noise ratio) +as CBR with +<option>vbitrate</option>=infinity and the default <option>vqmin</option> +of 2. +</para> + +<para> +The problem with constant quantizing is that it uses the given quantizer +whether the macroblock needs it or not. That is, it might be possible +to use a higher quantizer on a macroblock without sacrificing visual +quality. Why waste the bits on an unnecessarily low quantizer? Your +CPU has as many cycles as there is time, but there is only so many bits +on your hard disk. +</para> + +<para> +With a two pass encode, the first pass will rip the movie as though it +were CBR, but it will keep a log of properties for each frame. This +data is then used during the second pass in order to make intelligent +decisions about which quantizers to use. During fast action or high +detail scenes, higher quantizers will likely be used, and during +slow moving or low detail scenes, lower quantizers will be used. +Normally, the amount of motion is much more important than the +amount of detail. +</para> + +<para> +If you use <option>vqscale=2</option>, then you are wasting bits. If you +use <option>vqscale=3</option>, then you are not getting the highest +quality rip. Suppose you rip a DVD at <option>vqscale=3</option>, and +the result is 1800Kbit. If you do a two pass encode with +<option>vbitrate=1800</option>, the resulting video will have +<emphasis role="bold">higher quality</emphasis> for the +<emphasis role="bold">same bitrate</emphasis>. +</para> + +<para> +Since you are now convinced that two pass is the way to go, the real +question now is what bitrate to use? The answer is that there is no +single answer. Ideally you want to choose a bitrate that yields the +best balance between quality and file size. This is going to vary +depending on the source video. +</para> + +<para> +If size does not matter, a good starting point for a very high quality +rip is about 2000Kbit plus or minus 200Kbit. +For fast action or high detail source video, or if you just have a very +critical eye, you might decide on 2400 or 2600. +For some DVDs, you might not notice a difference at 1400Kbit. It is a +good idea to experiment with scenes at different bitrates to get a feel. +</para> + +<para> +If you aim at a certain size, you will have to somehow calculate the bitrate. +But before that, you need to know how much space you should reserve for the +audio track(s), so you should +<link linkend="menc-feat-dvd-mpeg4-audio">rip those</link> first. +You can compute the bitrate with the following equation: +<systemitem>bitrate = (target_size_in_Mbytes - sound_size_in_Mbytes) * +1024 * 1024 / length_in_secs * 8 / 1000</systemitem> +For instance, to squeeze a two-hour movie onto a 702MB CD, with 60MB +of audio track, the video bitrate will have to be: +<systemitem>(702 - 60) * 1024 * 1024 / (120*60) * 8 / 1000 += 740kbps</systemitem> +</para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-constraints"> <title>Constraints for efficient encoding</title> <para> - Due to the nature of MPEG-type compression, there are various - constraints you should follow for maximal quality. - MPEG splits the video up into 16x16 squares called macroblocks, - each composed of 4 8x8 blocks of luma (intensity) information and two - half-resolution 8x8 chroma (color) blocks (one for red-cyan axis and - the other for the blue-yellow axis). - Even if your movie width and height are not multiples of 16, the - encoder will use enough 16x16 macroblocks to cover the whole picture - area, and the extra space will go to waste. - So in the interests of maximizing quality at a fixed filesize, it is - a bad idea to use dimensions that are not multiples of 16. -</para> - -<para> - Most DVDs also have some degree of black borders at the edges. Leaving - these in place will hurt quality <emphasis role="bold">a lot</emphasis> - in several ways. +Due to the nature of MPEG-type compression, there are various +constraints you should follow for maximal quality. +MPEG splits the video up into 16x16 squares called macroblocks, +each composed of 4 8x8 blocks of luma (intensity) information and two +half-resolution 8x8 chroma (color) blocks (one for red-cyan axis and +the other for the blue-yellow axis). +Even if your movie width and height are not multiples of 16, the +encoder will use enough 16x16 macroblocks to cover the whole picture +area, and the extra space will go to waste. +So in the interests of maximizing quality at a fixed filesize, it is +a bad idea to use dimensions that are not multiples of 16. +</para> + +<para> +Most DVDs also have some degree of black borders at the edges. Leaving +these in place will hurt quality <emphasis role="bold">a lot</emphasis> +in several ways. </para> <orderedlist> <listitem> -<para> + <para> MPEG-type compression is also highly dependent on frequency domain transformations, in particular the Discrete Cosine Transform (DCT), which is similar to the Fourier transform. This sort of encoding is @@ -461,33 +477,33 @@ has a hard time with sharp edges. In order to encode them it must use many more bits, or else an artifact known as ringing will appear. -</para> - -<para> + </para> + + <para> The frequency transform (DCT) takes place separately on each macroblock (actually each block), so this problem only applies when the sharp edge is inside a block. If your black borders begin exactly at multiple-of-16 pixel boundaries, this is not a problem. However, the black borders on DVDs rarely come nicely aligned, so in practice you will always need to crop to avoid this penalty. -</para> + </para> </listitem> </orderedlist> <para> - In addition to frequency domain transforms, MPEG-type compression uses - motion vectors to represent the change from one frame to the next. - Motion vectors naturally work much less efficiently for new content - coming in from the edges of the picture, because it is not present in - the previous frame. As long as the picture extends all the way to the - edge of the encoded region, motion vectors have no problem with - content moving out the edges of the picture. However, in the presence - of black borders, there can be trouble: +In addition to frequency domain transforms, MPEG-type compression uses +motion vectors to represent the change from one frame to the next. +Motion vectors naturally work much less efficiently for new content +coming in from the edges of the picture, because it is not present in +the previous frame. As long as the picture extends all the way to the +edge of the encoded region, motion vectors have no problem with +content moving out the edges of the picture. However, in the presence +of black borders, there can be trouble: </para> <orderedlist continuation="continues"> <listitem> -<para> + <para> For each macroblock, MPEG-type compression stores a vector identifying which part of the previous frame should be copied into this macroblock as a base for predicting the next frame. Only the @@ -499,72 +515,71 @@ motion vector will not be used at all and all the changes in this macroblock will have to be coded explicitly. Either way, encoding efficiency is greatly reduced. -</para> - -<para> + </para> + + <para> Again, this problem only applies if black borders do not line up on multiple-of-16 boundaries. -</para> + </para> </listitem> <listitem> -<para> + <para> Finally, suppose we have a macroblock in the interior of the picture, and an object is moving into this block from near the edge of the image. MPEG-type coding cannot say "copy the part that is inside the picture but not the black border." So the black border will get copied inside too, and lots of bits will have to be spent encoding the part of the picture that is supposed to be there. -</para> - -<para> + </para> + + <para> If the picture runs all the way to the edge of the encoded area, MPEG has special optimizations to repeatedly copy the pixels at the edge of the picture when a motion vector comes from outside the encoded area. This feature becomes useless when the movie has black borders. Unlike problems 1 and 2, aligning the borders at multiples of 16 does not help here. -</para> + </para> </listitem> -<listitem> -<para> +<listitem><para> Despite the borders being entirely black and never changing, there is at least a minimal amount of overhead involved in having more macroblocks. -</para> -</listitem> +</para></listitem> </orderedlist> <para> - For all of these reasons, it is recommended to fully crop black - borders. Further, if there is an area of noise/distortion at the edge - of the picture, cropping this will improve encoding efficiency as - well. Videophile purists who want to preserve the original as close as - possible may object to this cropping, but unless you plan to encode at - constant quantizer, the quality you gain from cropping will - considerably exceed the amount of information lost at the edges. +For all of these reasons, it is recommended to fully crop black +borders. Further, if there is an area of noise/distortion at the edge +of the picture, cropping this will improve encoding efficiency as +well. Videophile purists who want to preserve the original as close as +possible may object to this cropping, but unless you plan to encode at +constant quantizer, the quality you gain from cropping will +considerably exceed the amount of information lost at the edges. </para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-crop"> <title>Cropping and Scaling</title> <para> - Recall from the previous section that the final picture size you - encode should be a multiple of 16 (in both width and height). - This can be achieved by cropping, scaling, or a combination of both. -</para> - -<para> - When cropping, there are a few guidelines that must be followed to - avoid damaging your movie. - The normal YUV format, 4:2:0, stores chroma (color) information - subsampled, i.e. chroma is only sampled half as often in each - direction as luma (intensity) information. - Observe this diagram, where L indicates luma sampling points and C - chroma. +Recall from the previous section that the final picture size you +encode should be a multiple of 16 (in both width and height). +This can be achieved by cropping, scaling, or a combination of both. +</para> + +<para> +When cropping, there are a few guidelines that must be followed to +avoid damaging your movie. +The normal YUV format, 4:2:0, stores chroma (color) information +subsampled, i.e. chroma is only sampled half as often in each +direction as luma (intensity) information. +Observe this diagram, where L indicates luma sampling points and C +chroma. </para> <informaltable> @@ -641,18 +656,18 @@ </informaltable> <para> - As you can see, rows and columns of the image naturally come in pairs. - Thus your crop offsets and dimensions <emphasis>must</emphasis> be - even numbers. - If they are not, the chroma will no longer line up correctly with the - luma. - In theory, it is possible to crop with odd offsets, but it requires - resampling the chroma which is potentially a lossy operation and not - supported by the crop filter. -</para> - -<para> - Further, interlaced video is sampled as follows: +As you can see, rows and columns of the image naturally come in pairs. +Thus your crop offsets and dimensions <emphasis>must</emphasis> be +even numbers. +If they are not, the chroma will no longer line up correctly with the +luma. +In theory, it is possible to crop with odd offsets, but it requires +resampling the chroma which is potentially a lossy operation and not +supported by the crop filter. +</para> + +<para> +Further, interlaced video is sampled as follows: </para> <informaltable> @@ -893,164 +908,169 @@ </informaltable> <para> - As you can see, the pattern does not repeat until after 4 lines. - So for interlaced video, your y-offset and height for cropping must - be multiples of 4. -</para> - -<para> - Native DVD resolution is 720x480 for NTSC, and 720x576 for PAL, but - there is an aspect flag that specifies whether it is full-screen (4:3) or - wide-screen (16:9). Many (if not most) widescreen DVDs are not strictly - 16:9, and will be either 1.85:1 or 2.35:1 (cinescope). This means that - there will be black bands in the video that will need to be cropped out. -</para> - -<para> - <application>MPlayer</application> provides a crop detection filter that - will determine the crop rectangle (<option>-vf cropdetect</option>). - Run <application>MPlayer</application> with - <option>-vf cropdetect</option> and it will print out the crop - settings to remove the borders. - You should let the movie run long enough that the whole picture - area is used, in order to get accurate crop values. -</para> - -<para> - Then, test the values you get with <application>MPlayer</application>, - using the command line which was printed by - <option>cropdetect</option>, and adjust the rectangle as needed. - The <option>rectangle</option> filter can help by allowing you to - interactively position the crop rectangle over your movie. - Remember to follow the above divisibility guidelines so that you - do not misalign the chroma planes. -</para> - -<para> - In certain cases, scaling may be undesirable. - Scaling in the vertical direction is difficult with interlaced - video, and if you wish to preserve the interlacing, you should - usually refrain from scaling. - If you will not be scaling but you still want to use multiple-of-16 - dimensions, you will have to overcrop. - Do not undercrop, since black borders are very bad for encoding! -</para> - -<para> - Because MPEG-4 uses 16x16 macroblocks, you will want to make sure that each - dimension of the video you are encoding is a multiple of 16 or else you - will be degrading quality, especially at lower bitrates. You can do this - by rounding the width and height of the crop rectangle down to the nearest - multiple of 16. - As stated earlier, when cropping, you will want to increase the Y offset by - half the difference of the old and the new height so that the resulting - video is taken from the center of the frame. And because of the way DVD - video is sampled, make sure the offset is an even number. (In fact, as a - rule, never use odd values for any parameter when you are cropping and - scaling video.) If you are not comfortable throwing a few extra pixels - away, you might prefer instead to scale the video instead. We will look - at this in our example below. - You can actually let the <option>cropdetect</option> filter do all of the - above for you, as it has an optional <option>round</option> parameter that - is equal to 16 by default. -</para> - -<para> - Also, be careful about "half black" pixels at the edges. Make sure you - crop these out too, or else you will be wasting bits there that - are better spent elsewhere. -</para> - -<para> - After all is said and done, you will probably end up with video whose pixels - are not quite 1.85:1 or 2.35:1, but rather something close to that. You - could calculate the new aspect ratio manually, but - <application>MEncoder</application> offers an option for <systemitem - class="library">libavcodec</systemitem> called <option>autoaspect</option> - that will do this for you. Absolutely do not scale this video up in order to - square the pixels unless you like to waste your hard disk space. Scaling - should be done on playback, and the player will use the aspect stored in - the AVI to determine the correct resolution. - Unfortunately, not all players enforce this auto-scaling information, - therefore you may still want to rescale. +As you can see, the pattern does not repeat until after 4 lines. +So for interlaced video, your y-offset and height for cropping must +be multiples of 4. +</para> + +<para> +Native DVD resolution is 720x480 for NTSC, and 720x576 for PAL, but +there is an aspect flag that specifies whether it is full-screen (4:3) or +wide-screen (16:9). Many (if not most) widescreen DVDs are not strictly +16:9, and will be either 1.85:1 or 2.35:1 (cinescope). This means that +there will be black bands in the video that will need to be cropped out. +</para> + +<para> +<application>MPlayer</application> provides a crop detection filter that +will determine the crop rectangle (<option>-vf cropdetect</option>). +Run <application>MPlayer</application> with +<option>-vf cropdetect</option> and it will print out the crop +settings to remove the borders. +You should let the movie run long enough that the whole picture +area is used, in order to get accurate crop values. +</para> + +<para> +Then, test the values you get with <application>MPlayer</application>, +using the command line which was printed by +<option>cropdetect</option>, and adjust the rectangle as needed. +The <option>rectangle</option> filter can help by allowing you to +interactively position the crop rectangle over your movie. +Remember to follow the above divisibility guidelines so that you +do not misalign the chroma planes. +</para> + +<para> +In certain cases, scaling may be undesirable. +Scaling in the vertical direction is difficult with interlaced +video, and if you wish to preserve the interlacing, you should +usually refrain from scaling. +If you will not be scaling but you still want to use multiple-of-16 +dimensions, you will have to overcrop. +Do not undercrop, since black borders are very bad for encoding! +</para> + +<para> +Because MPEG-4 uses 16x16 macroblocks, you will want to make sure that each +dimension of the video you are encoding is a multiple of 16 or else you +will be degrading quality, especially at lower bitrates. You can do this +by rounding the width and height of the crop rectangle down to the nearest +multiple of 16. +As stated earlier, when cropping, you will want to increase the Y offset by +half the difference of the old and the new height so that the resulting +video is taken from the center of the frame. And because of the way DVD +video is sampled, make sure the offset is an even number. (In fact, as a +rule, never use odd values for any parameter when you are cropping and +scaling video.) If you are not comfortable throwing a few extra pixels +away, you might prefer instead to scale the video instead. We will look +at this in our example below. +You can actually let the <option>cropdetect</option> filter do all of the +above for you, as it has an optional <option>round</option> parameter that +is equal to 16 by default. +</para> + +<para> +Also, be careful about "half black" pixels at the edges. Make sure you +crop these out too, or else you will be wasting bits there that +are better spent elsewhere. +</para> + +<para> +After all is said and done, you will probably end up with video whose pixels +are not quite 1.85:1 or 2.35:1, but rather something close to that. You +could calculate the new aspect ratio manually, but +<application>MEncoder</application> offers an option for <systemitem +class="library">libavcodec</systemitem> called <option>autoaspect</option> +that will do this for you. Absolutely do not scale this video up in order to +square the pixels unless you like to waste your hard disk space. Scaling +should be done on playback, and the player will use the aspect stored in +the AVI to determine the correct resolution. +Unfortunately, not all players enforce this auto-scaling information, +therefore you may still want to rescale. </para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-resolution-bitrate"> <title>Choosing resolution and bitrate</title> <para> - If you will not be encoding in constant quantizer mode, you need to - select a bitrate. - The concept of bitrate is quite simple. - It is the (average) number of bits that will be consumed to store your - movie, per second. - Normally bitrate is measured in kilobits (1000 bits) per second. - The size of your movie on disk is the bitrate times the length of the - movie in time, plus a small amount of "overhead" (see the section on - <link linkend="menc-feat-dvd-mpeg4-muxing-avi-limitations">the AVI container</link> - for instance). - Other parameters such as scaling, cropping, etc. will - <emphasis role="bold">not</emphasis> alter the file size unless you - change the bitrate as well!. -</para> -<para> - Bitrate does <emphasis role="bold">not</emphasis> scale proportionally - to resolution. - That is to say, a 320x240 file at 200 kbit/sec will not be the same - quality as the same movie at 640x480 and 800 kbit/sec! - There are two reasons for this: +If you will not be encoding in constant quantizer mode, you need to +select a bitrate. +The concept of bitrate is quite simple. +It is the (average) number of bits that will be consumed to store your +movie, per second. +Normally bitrate is measured in kilobits (1000 bits) per second. +The size of your movie on disk is the bitrate times the length of the +movie in time, plus a small amount of "overhead" (see the section on +<link linkend="menc-feat-dvd-mpeg4-muxing-avi-limitations">the AVI container</link> +for instance). +Other parameters such as scaling, cropping, etc. will +<emphasis role="bold">not</emphasis> alter the file size unless you +change the bitrate as well!. +</para> + +<para> +Bitrate does <emphasis role="bold">not</emphasis> scale proportionally +to resolution. +That is to say, a 320x240 file at 200 kbit/sec will not be the same +quality as the same movie at 640x480 and 800 kbit/sec! +There are two reasons for this: <orderedlist> - <listitem><para> - <emphasis role="bold">Perceptual</emphasis>: You notice MPEG - artifacts more if they are scaled up bigger! - Artifacts appear on the scale of blocks (8x8). - Your eye will not see errors in 4800 small blocks as easily as it - sees errors in 1200 large blocks (assuming you will be scaling both - to fullscreen). - </para></listitem> - <listitem><para> - <emphasis role="bold">Theoretical</emphasis>: When you scale down - an image but still use the same size (8x8) blocks for the frequency - space transform, you move more data to the high frequency bands. - Roughly speaking, each pixel contains more of the detail than it - did before. - So even though your scaled-down picture contains 1/4 the information - in the spacial directions, it could still contain a large portion - of the information in the frequency domain (assuming that the high - frequencies were underutilized in the original 640x480 image). - </para></listitem> - </orderedlist> -</para> -<para> - Past guides have recommended choosing a bitrate and resolution based - on a "bits per pixel" approach, but this is usually not valid due to - the above reasons. - A better estimate seems to be that bitrates scale proportional to the - square root of resolution, so that 320x240 and 400 kbit/sec would be - comparable to 640x480 at 800 kbit/sec. - However this has not been verified with theoretical or empirical - rigor. - Further, given that movies vary greatly with regard to noise, detail, - degree of motion, etc., it is futile to make general recommendations - for bits per length-of-diagonal (the analog of bits per pixel, - using the square root). -</para> -<para> - So far we have discussed the difficulty of choosing a bitrate and - resolution. +<listitem><para> + <emphasis role="bold">Perceptual</emphasis>: You notice MPEG + artifacts more if they are scaled up bigger! + Artifacts appear on the scale of blocks (8x8). + Your eye will not see errors in 4800 small blocks as easily as it + sees errors in 1200 large blocks (assuming you will be scaling both + to fullscreen). +</para></listitem> +<listitem><para> + <emphasis role="bold">Theoretical</emphasis>: When you scale down + an image but still use the same size (8x8) blocks for the frequency + space transform, you move more data to the high frequency bands. + Roughly speaking, each pixel contains more of the detail than it + did before. + So even though your scaled-down picture contains 1/4 the information + in the spacial directions, it could still contain a large portion + of the information in the frequency domain (assuming that the high + frequencies were underutilized in the original 640x480 image). +</para></listitem> +</orderedlist> +</para> + +<para> +Past guides have recommended choosing a bitrate and resolution based +on a "bits per pixel" approach, but this is usually not valid due to +the above reasons. +A better estimate seems to be that bitrates scale proportional to the +square root of resolution, so that 320x240 and 400 kbit/sec would be +comparable to 640x480 at 800 kbit/sec. +However this has not been verified with theoretical or empirical +rigor. +Further, given that movies vary greatly with regard to noise, detail, +degree of motion, etc., it is futile to make general recommendations +for bits per length-of-diagonal (the analog of bits per pixel, +using the square root). +</para> +<para> +So far we have discussed the difficulty of choosing a bitrate and +resolution. </para> <sect3 id="menc-feat-dvd-mpeg4-resolution-bitrate-compute"> <title>Computing the resolution</title> -<para> - The following steps will guide you in computing the resolution of your - encode without distorting the video too much, by taking into account several - types of information about the source video. - First, you should compute the encoded aspect ratio: - <systemitem>ARc = (Wc x (ARa / PRdvd )) / Hc</systemitem> + +<para> +The following steps will guide you in computing the resolution of your +encode without distorting the video too much, by taking into account several +types of information about the source video. +First, you should compute the encoded aspect ratio: +<systemitem>ARc = (Wc x (ARa / PRdvd )) / Hc</systemitem> + <itemizedlist> <title>where:</title> <listitem><para> @@ -1067,219 +1087,220 @@ </para> <para> - Then, you can compute the X and Y resolution, according to a certain - Compression Quality (CQ) factor: - <systemitem>ResY = INT(SQRT( 1000*Bitrate/25/ARc/CQ )/16) * 16</systemitem> - and - <systemitem>ResX = INT( ResY * ARc / 16) * 16</systemitem> -</para> - -<para> - Okay, but what is the CQ? - The CQ represents the number of bits per pixel and per frame of the encode. - Roughly speaking, the greater the CQ, the less the likelihood to see - encoding artifacts. - However, if you have a target size for your movie (1 or 2 CDs for instance), - there is a limited total number of bits that you can spend; therefore it is - necessary to find a good tradeoff between compressibility and quality. -</para> - -<para> - The CQ depends on the bitrate, the video codec efficiency and the - movie resolution. - In order to raise the CQ, typically you would downscale the movie given that the - bitrate is computed in function of the target size and the length of the - movie, which are constant. - With MPEG-4 ASP codecs such as <systemitem class="library">Xvid</systemitem> - and <systemitem class="library">libavcodec</systemitem>, a CQ below 0.18 - usually results in a pretty blocky picture, because there - are not enough bits to code the information of each macroblock. (MPEG4, like - many other codecs, groups pixels by blocks of several pixels to compress the - image; if there are not enough bits, the edges of those blocks are - visible.) - It is therefore wise to take a CQ ranging from 0.20 to 0.22 for a 1 CD rip, - and 0.26-0.28 for 2 CDs rip with standard encoding options. - More advanced encoding options such as those listed here for - <link linkend="menc-feat-mpeg4-lavc-example-settings"><systemitem class="library">libavcodec</systemitem></link> - and +Then, you can compute the X and Y resolution, according to a certain +Compression Quality (CQ) factor: +<systemitem>ResY = INT(SQRT( 1000*Bitrate/25/ARc/CQ )/16) * 16</systemitem> +and +<systemitem>ResX = INT( ResY * ARc / 16) * 16</systemitem> +</para> + +<para> +Okay, but what is the CQ? +The CQ represents the number of bits per pixel and per frame of the encode. +Roughly speaking, the greater the CQ, the less the likelihood to see +encoding artifacts. +However, if you have a target size for your movie (1 or 2 CDs for instance), +there is a limited total number of bits that you can spend; therefore it is +necessary to find a good tradeoff between compressibility and quality. +</para> + +<para> +The CQ depends on the bitrate, the video codec efficiency and the +movie resolution. +In order to raise the CQ, typically you would downscale the movie given that the +bitrate is computed in function of the target size and the length of the +movie, which are constant. +With MPEG-4 ASP codecs such as <systemitem class="library">Xvid</systemitem> +and <systemitem class="library">libavcodec</systemitem>, a CQ below 0.18 +usually results in a pretty blocky picture, because there +are not enough bits to code the information of each macroblock. (MPEG4, like +many other codecs, groups pixels by blocks of several pixels to compress the +image; if there are not enough bits, the edges of those blocks are +visible.) +It is therefore wise to take a CQ ranging from 0.20 to 0.22 for a 1 CD rip, +and 0.26-0.28 for 2 CDs rip with standard encoding options. +More advanced encoding options such as those listed here for +<link linkend="menc-feat-mpeg4-lavc-example-settings"><systemitem class="library">libavcodec</systemitem></link> +and <link linkend="menc-feat-xvid-example-settings"><systemitem class="library">Xvid</systemitem></link> - should make it possible to get the same quality with CQ ranging from - 0.18 to 0.20 for a 1 CD rip, and 0.24 to 0.26 for a 2 CD rip. - With MPEG-4 ASP codecs such as <systemitem class="library">x264</systemitem>, - you can use a CQ ranging from 0.14 to 0.16 with standard encoding options, - and should be able to go as low as 0.10 to 0.12 with - <link linkend="menc-feat-x264-example-settings"><systemitem class="library">x264</systemitem>'s advanced encoding settings</link>. -</para> - -<para> - Please take note that the CQ is just an indicative figure, as depending on - the encoded content, a CQ of 0.18 may look just fine for a Bergman, contrary - to a movie such as The Matrix, which contains many high-motion scenes. - On the other hand, it is worthless to raise CQ higher than 0.30 as you would - be wasting bits without any noticeable quality gain. - Also note that as mentioned earlier in this guide, low resolution videos - need a bigger CQ (compared to, for instance, DVD resolution) to look good. +should make it possible to get the same quality with CQ ranging from +0.18 to 0.20 for a 1 CD rip, and 0.24 to 0.26 for a 2 CD rip. +With MPEG-4 ASP codecs such as <systemitem class="library">x264</systemitem>, +you can use a CQ ranging from 0.14 to 0.16 with standard encoding options, +and should be able to go as low as 0.10 to 0.12 with +<link linkend="menc-feat-x264-example-settings"><systemitem class="library">x264</systemitem>'s advanced encoding settings</link>. +</para> + +<para> +Please take note that the CQ is just an indicative figure, as depending on +the encoded content, a CQ of 0.18 may look just fine for a Bergman, contrary +to a movie such as The Matrix, which contains many high-motion scenes. +On the other hand, it is worthless to raise CQ higher than 0.30 as you would +be wasting bits without any noticeable quality gain. +Also note that as mentioned earlier in this guide, low resolution videos +need a bigger CQ (compared to, for instance, DVD resolution) to look good. </para> </sect3> - </sect2> +<!-- ********** --> + <sect2 id="menc-feat-dvd-mpeg4-filtering"> <title>Filtering</title> <para> - Learning how to use <application>MEncoder</application>'s video filters - is essential to producing good encodes. - All video processing is performed through the filters -- cropping, - scaling, color adjustment, noise removal, sharpening, deinterlacing, - telecine, inverse telecine, and deblocking, just to name a few. - Along with the vast number of supported input formats, the variety of - filters available in <application>MEncoder</application> is one of its - main advantages over other similar programs. -</para> - -<para> - Filters are loaded in a chain using the -vf option: - - <screen>-vf filter1=options,filter2=options,...</screen> - - Most filters take several numeric options separated by colons, but - the syntax for options varies from filter to filter, so read the man - page for details on the filters you wish to use. -</para> - -<para> - Filters operate on the video in the order they are loaded. - For example, the following chain: - - <screen>-vf crop=688:464:12:4,scale=640:464</screen> - - will first crop the 688x464 region of the picture with upper-left - corner at (12,4), and then scale the result down to 640x464. -</para> - -<para> - Certain filters need to be loaded at or near the beginning of the - filter chain, in order to take advantage of information from the - video decoder that will be lost or invalidated by other filters. - The principal examples are <option>pp</option> (postprocessing, only - when it is performing deblock or dering operations), - <option>spp</option> (another postprocessor to remove MPEG artifacts), - <option>pullup</option> (inverse telecine), and - <option>softpulldown</option> (for converting soft telecine to hard - telecine). -</para> - -<para> - In general, you want to do as little filtering as possible to the movie - in order to remain close to the original DVD source. Cropping is often - necessary (as described above), but avoid to scale the video. Although - scaling down is sometimes preferred to using higher quantizers, we want - to avoid both these things: remember that we decided from the start to - trade bits for quality. -</para> - -<para> - Also, do not adjust gamma, contrast, brightness, etc. What looks good - on your display may not look good on others. These adjustments should - be done on playback only. -</para> - -<para> - One thing you might want to do, however, is pass the video through a - very light denoise filter, such as <option>-vf hqdn3d=2:1:2</option>. - Again, it is a matter of putting those bits to better use: why waste them - encoding noise when you can just add that noise back in during playback? - Increasing the parameters for <option>hqdn3d</option> will further - improve compressibility, but if you increase the values too much, you - risk degrading the image visibily. The suggested values above - (<option>2:1:2</option>) are quite conservative; you should feel free to - experiment with higher values and observe the results for yourself. -</para> - +Learning how to use <application>MEncoder</application>'s video filters +is essential to producing good encodes. +All video processing is performed through the filters -- cropping, +scaling, color adjustment, noise removal, sharpening, deinterlacing, +telecine, inverse telecine, and deblocking, just to name a few. +Along with the vast number of supported input formats, the variety of +filters available in <application>MEncoder</application> is one of its +main advantages over other similar programs. +</para> + +<para> +Filters are loaded in a chain using the -vf option: + +<screen>-vf filter1=options,filter2=options,...</screen> + +Most filters take several numeric options separated by colons, but +the syntax for options varies from filter to filter, so read the man +page for details on the filters you wish to use. +</para> + +<para> +Filters operate on the video in the order they are loaded. +For example, the following chain: + +<screen>-vf crop=688:464:12:4,scale=640:464</screen> + +will first crop the 688x464 region of the picture with upper-left +corner at (12,4), and then scale the result down to 640x464. +</para> + +<para> +Certain filters need to be loaded at or near the beginning of the +filter chain, in order to take advantage of information from the +video decoder that will be lost or invalidated by other filters. +The principal examples are <option>pp</option> (postprocessing, only +when it is performing deblock or dering operations), +<option>spp</option> (another postprocessor to remove MPEG artifacts), +<option>pullup</option> (inverse telecine), and +<option>softpulldown</option> (for converting soft telecine to hard telecine). +</para> + +<para> +In general, you want to do as little filtering as possible to the movie +in order to remain close to the original DVD source. Cropping is often +necessary (as described above), but avoid to scale the video. Although +scaling down is sometimes preferred to using higher quantizers, we want +to avoid both these things: remember that we decided from the start to +trade bits for quality. +</para> + +<para> +Also, do not adjust gamma, contrast, brightness, etc. What looks good +on your display may not look good on others. These adjustments should +be done on playback only. +</para> + +<para> +One thing you might want to do, however, is pass the video through a +very light denoise filter, such as <option>-vf hqdn3d=2:1:2</option>. +Again, it is a matter of putting those bits to better use: why waste them +encoding noise when you can just add that noise back in during playback? +Increasing the parameters for <option>hqdn3d</option> will further +improve compressibility, but if you increase the values too much, you +risk degrading the image visibily. The suggested values above +(<option>2:1:2</option>) are quite conservative; you should feel free to +experiment with higher values and observe the results for yourself. +</para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-interlacing"> <title>Interlacing and Telecine</title> <para> - Almost all movies are shot at 24 fps. Because NTSC is 30000/1001 fps, some - processing must be done to this 24 fps video to make it run at the correct - NTSC framerate. The process is called 3:2 pulldown, commonly referred to - as telecine (because pulldown is often applied during the telecine - process), and, naively described, it works by slowing the film down to - 24000/1001 fps, and repeating every fourth frame. -</para> - -<para> - No special processing, however, is done to the video for PAL DVDs, which - run at 25 fps. (Technically, PAL can be telecined, called 2:2 pulldown, - but this does not become an issue in practice.) The 24 fps film is simply - played back at 25 fps. The result is that the movie runs slightly faster, - but unless you are an alien, you probably will not notice the difference. - Most PAL DVDs have pitch-corrected audio, so when they are played back at - 25 fps things will sound right, even though the audio track (and hence the - whole movie) has a running time that is 4% less than NTSC DVDs. -</para> - -<para> - Because the video in a PAL DVD has not been altered, you need not worry - much about framerate. The source is 25 fps, and your rip will be 25 - fps. However, if you are ripping an NTSC DVD movie, you may need to - apply inverse telecine. -</para> - -<para> - For movies shot at 24 fps, the video on the NTSC DVD is either telecined - 30000/1001, or else it is progressive 24000/1001 fps and intended to be telecined - on-the-fly by a DVD player. On the other hand, TV series are usually - only interlaced, not telecined. This is not a hard rule: some TV series - are interlaced (such as Buffy the Vampire Slayer) whereas some are a - mixture of progressive and interlaced (such as Angel, or 24). -</para> - -<para> - It is highly recommended that you read the section on - <link linkend="menc-feat-telecine">How to deal with telecine and interlacing in NTSC DVDs</link> - to learn how to handle the different possibilities. -</para> - -<para> - However, if you are mostly just ripping movies, likely you are either - dealing with 24 fps progressive or telecined video, in which case you can - use the <option>pullup</option> filter <option>-vf - pullup,softskip</option>. -</para> - +Almost all movies are shot at 24 fps. Because NTSC is 30000/1001 fps, some +processing must be done to this 24 fps video to make it run at the correct +NTSC framerate. The process is called 3:2 pulldown, commonly referred to +as telecine (because pulldown is often applied during the telecine +process), and, naively described, it works by slowing the film down to +24000/1001 fps, and repeating every fourth frame. +</para> + +<para> +No special processing, however, is done to the video for PAL DVDs, which +run at 25 fps. (Technically, PAL can be telecined, called 2:2 pulldown, +but this does not become an issue in practice.) The 24 fps film is simply +played back at 25 fps. The result is that the movie runs slightly faster, +but unless you are an alien, you probably will not notice the difference. +Most PAL DVDs have pitch-corrected audio, so when they are played back at +25 fps things will sound right, even though the audio track (and hence the +whole movie) has a running time that is 4% less than NTSC DVDs. +</para> + +<para> +Because the video in a PAL DVD has not been altered, you need not worry +much about framerate. The source is 25 fps, and your rip will be 25 +fps. However, if you are ripping an NTSC DVD movie, you may need to +apply inverse telecine. +</para> + +<para> +For movies shot at 24 fps, the video on the NTSC DVD is either telecined +30000/1001, or else it is progressive 24000/1001 fps and intended to be +telecined on-the-fly by a DVD player. On the other hand, TV series are usually +only interlaced, not telecined. This is not a hard rule: some TV series +are interlaced (such as Buffy the Vampire Slayer) whereas some are a +mixture of progressive and interlaced (such as Angel, or 24). +</para> + +<para> +It is highly recommended that you read the section on +<link linkend="menc-feat-telecine">How to deal with telecine and interlacing in NTSC DVDs</link> +to learn how to handle the different possibilities. +</para> + +<para> +However, if you are mostly just ripping movies, likely you are either +dealing with 24 fps progressive or telecined video, in which case you can +use the <option>pullup</option> filter <option>-vf +pullup,softskip</option>. +</para> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-dvd-mpeg4-encoding-interlaced"> <title>Encoding interlaced video</title> <para> - If the movie you want to encode is interlaced (NTSC video or - PAL video), you will need to choose whether you want to - deinterlace or not. - While deinterlacing will make your movie usable on progressive - scan displays such a computer monitors and projectors, it comes - at a cost: The fieldrate of 50 or 60000/1001 fields per second - is halved to 25 or 30000/1001 frames per second, and roughly half of - the information in your movie will be lost during scenes with - significant motion. -</para> - -<para> - Therefore, if you are encoding for high quality archival purposes, - it is recommended not to deinterlace. - You can always deinterlace the movie at playback time when - displaying it on progressive scan devices. - The power of currently available computers forces players to use a - deinterlacing filter, which results in a slight degradation in - image quality. - But future players will be able to mimic the interlaced display of - a TV, deinterlacing to full fieldrate and interpolating 50 or - 60000/1001 entire frames per second from the interlaced video. +If the movie you want to encode is interlaced (NTSC video or +PAL video), you will need to choose whether you want to +deinterlace or not. +While deinterlacing will make your movie usable on progressive +scan displays such a computer monitors and projectors, it comes +at a cost: The fieldrate of 50 or 60000/1001 fields per second +is halved to 25 or 30000/1001 frames per second, and roughly half of +the information in your movie will be lost during scenes with +significant motion. +</para> + +<para> +Therefore, if you are encoding for high quality archival purposes, +it is recommended not to deinterlace. +You can always deinterlace the movie at playback time when +displaying it on progressive scan devices. +The power of currently available computers forces players to use a +deinterlacing filter, which results in a slight degradation in +image quality. +But future players will be able to mimic the interlaced display of +a TV, deinterlacing to full fieldrate and interpolating 50 or +60000/1001 entire frames per second from the interlaced video. </para> <para> @@ -1302,19 +1323,19 @@ <para> With these things in mind, here is our first example: -</para> <screen> - mencoder <replaceable>capture.avi</replaceable> -mc 0 -oac lavc -ovc lavc -lavcopts \ - vcodec=mpeg2video:vbitrate=6000:ilme:ildct:acodec=mp2:abitrate=224 +mencoder <replaceable>capture.avi</replaceable> -mc 0 -oac lavc -ovc lavc -lavcopts \ + vcodec=mpeg2video:vbitrate=6000:ilme:ildct:acodec=mp2:abitrate=224 </screen> -<para> Note the <option>ilme</option> and <option>ildct</option> options. </para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-av-sync"> <title>Notes on Audio/Video synchronization</title> + <para> <application>MEncoder</application>'s audio/video synchronization algorithms were designed with the intention of recovering files with @@ -1329,6 +1350,7 @@ you are only working with good sources (DVD, TV capture, high quality MPEG-4 rips, etc) and not broken ASF/RM/MOV files. </para> + <para> If you want to further guard against strange frame skips and duplication, you can use both <option>-mc 0</option> and @@ -1339,9 +1361,11 @@ framerate! Therefore, using <option>-noskip</option> is not in general recommended. </para> -<para> -The so-called "three-pass" audio encoding which <application>MEncoder</application> -supports has been reported to cause A/V desync. + +<para> +The so-called "three-pass" audio encoding which +<application>MEncoder</application> supports has been reported to cause A/V +desync. This will definitely happen if it is used in conjunction with certain filters, therefore, it is now recommended <emphasis>not</emphasis> to use three-pass audio mode. @@ -1350,6 +1374,7 @@ If you have never heard of three-pass mode before, forget that we even mentioned it! </para> + <para> There have also been reports of A/V desync when encoding from stdin with <application>MEncoder</application>. @@ -1357,23 +1382,26 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-dvd-mpeg4-codec"> <title>Choosing the video codec</title> <para> - Which video codec is best to choose depends on several factors, - like size, quality, streamability, usability and popularity, some of - which widely depend on personal taste and technical constraints. +Which video codec is best to choose depends on several factors, +like size, quality, streamability, usability and popularity, some of +which widely depend on personal taste and technical constraints. </para> <itemizedlist> - <listitem><para> +<listitem> + <para> <emphasis role="bold">Compression efficiency</emphasis>: It is quite easy to understand that most newer-generation codecs are made to increase quality and compression. Therefore, the authors of this guide and many other people suggest that you cannot go wrong - <footnote id='fn-menc-feat-dvd-mpeg4-codec-cpu'> - <para>Be careful, however: Decoding DVD-resolution MPEG-4 AVC videos + <footnote id='fn-menc-feat-dvd-mpeg4-codec-cpu'><para> + Be careful, however: Decoding DVD-resolution MPEG-4 AVC videos requires a fast machine (i.e. a Pentium 4 over 1.5GHz or a Pentium M over 1GHz). </para></footnote> @@ -1387,18 +1415,21 @@ Likewise, you should get better quality using MPEG-4 ASP than you would with MPEG-2 codecs. </para> + <para> However, newer codecs which are in heavy development can suffer from bugs which have not yet been noticed and which can ruin an encode. This is simply the tradeoff for using bleeding-edge technology. </para> + <para> What is more, beginning to use a new codec requires that you spend some time becoming familiar with its options, so that you know what to adjust to achieve a desired picture quality. - </para></listitem> - - <listitem><para> + </para> +</listitem> + +<listitem><para> <emphasis role="bold">Hardware compatibility</emphasis>: It usually takes a long time for standalone video players to begin to include support for the latest video codecs. @@ -1409,9 +1440,10 @@ (Beware: Usually, not all MPEG-4 ASP features are supported). Please refer to the technical specs of your player (if they are available), or google around for more information. - </para></listitem> - - <listitem><para> +</para></listitem> + +<listitem> + <para> <emphasis role="bold">Best quality per encoding time</emphasis>: Codecs that have been around for some time (such as <systemitem class="library">libavcodec</systemitem> MPEG-4 and @@ -1421,11 +1453,13 @@ However, they may have some very advanced options that, if enabled, will make the encode really slow for marginal gains. </para> + <para> If you are after blazing speed you should stick around the default settings of the video codec (although you should still try the other options which are mentioned in other sections of this guide). </para> + <para> You may also consider choosing a codec which can do multi-threaded processing, though this is only useful for users of machines with @@ -1440,9 +1474,11 @@ <systemitem class="library">x264</systemitem> also allows multi-threaded encoding, which currently speeds up encoding by 15-30% (depending on the encoding settings) while lowering PSNR by about 0.05dB. - </para></listitem> - - <listitem><para> + </para> +</listitem> + +<listitem> + <para> <emphasis role="bold">Personal taste</emphasis>: This is where it gets almost irrational: For the same reason that some hung on to DivX 3 for years when newer codecs were already doing wonders, @@ -1457,224 +1493,238 @@ encoding options and codecs to find one that suits you best. The best codec is the one you master, and the one that looks best to your eyes on your display - <footnote id='fn-menc-feat-dvd-mpeg4-codec-playback'> - <para>The same encode may not look the same on someone else's monitor or + <footnote id='fn-menc-feat-dvd-mpeg4-codec-playback'><para> + The same encode may not look the same on someone else's monitor or when played back by a different decoder, so future-proof your encodes by - playing them back on different setups.</para></footnote>! - </para></listitem> + playing them back on different setups. + </para></footnote>! + </para> +</listitem> </itemizedlist> -<para> - Please refer to the section - <link linkend="menc-feat-selecting-codec">selecting codecs and container formats</link> - to get a list of supported codecs. + +<para> +Please refer to the section +<link linkend="menc-feat-selecting-codec">selecting codecs and container formats</link> +to get a list of supported codecs. </para> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-dvd-mpeg4-audio"> <title>Audio</title> <para> - Audio is a much simpler problem to solve: if you care about quality, just - leave it as is. - Even AC3 5.1 streams are at most 448Kbit/s, and they are worth every bit. - You might be tempted to transcode the audio to high quality Vorbis, but - just because you do not have an A/V receiver for AC3 pass-through today - does not mean you will not have one tomorrow. Future-proof your DVD rips by - preserving the AC3 stream. - You can keep the AC3 stream either by copying it directly into the video - stream <link linkend="menc-feat-mpeg4">during the encoding</link>. - You can also extract the AC3 stream in order to mux it into containers such - as NUT or Matroska. - <screen>mplayer <replaceable>source_file.vob</replaceable> -aid 129 -dumpaudio -dumpfile <replaceable>sound.ac3</replaceable></screen> - will dump into the file <replaceable>sound.ac3</replaceable> the - audio track number 129 from the file - <replaceable>source_file.vob</replaceable> (NB: DVD VOB files - usually use a different audio numbering, - which means that the VOB audio track 129 is the 2nd audio track of the file). -</para> - -<para> - But sometimes you truly have no choice but to further compress the - sound so that more bits can be spent on the video. - Most people choose to compress audio with either MP3 or Vorbis audio - codecs. - While the latter is a very space-efficient codec, MP3 is better supported - by hardware players, although this trend is changing. -</para> - -<para> - Do <emphasis>not</emphasis> use <option>-nosound</option> when encoding - a file with audio, even if you will be encoding and muxing audio - separately later. - Though it may work in ideal cases, using <option>-nosound</option> is - likely to hide some problems in your encoding command line setting. - In other words, having a soundtrack during your encode assures you that, - provided you do not see messages such as - <quote>Too many audio packets in the buffer</quote>, you will be able - to get proper sync. -</para> - -<para> - You need to have <application>MEncoder</application> process the sound. - You can for example copy the orignal soundtrack during the encode with - <option>-oac copy</option> or convert it to a "light" 4 kHz mono WAV - PCM with <option>-oac pcm -channels 1 -srate 4000</option>. - Otherwise, in some cases, it will generate a video file that will not sync - with the audio. - Such cases are when the number of video frames in the source file does - not match up to the total length of audio frames or whenever there - are discontinuities/splices where there are missing or extra audio frames. - The correct way to handle this kind of problem is to insert silence or - cut audio at these points. - However <application>MPlayer</application> cannot do that, so if you - demux the AC3 audio and encode it with a separate app (or dump it to PCM with - <application>MPlayer</application>), the splices will be left incorrect - and the only way to correct them is to drop/dup video frames at the - splice. - As long as <application>MEncoder</application> sees the audio when it is - encoding the video, it can do this dropping/duping (which is usually OK - since it takes place at full black/scenechange), but if - <application>MEncoder</application> cannot see the audio, it will just - process all frames as-is and they will not fit the final audio stream when - you for example merge your audio and video track into a Matroska file. -</para> - -<para> - First of all, you will have to convert the DVD sound into a WAV file that the - audio codec can use as input. - For example: - <screen>mplayer <replaceable>source_file.vob</replaceable> -ao pcm:file=<replaceable>destination_sound.wav</replaceable> -vc dummy -aid 1 -vo null</screen> - will dump the second audio track from the file - <replaceable>source_file.vob</replaceable> into the file - <replaceable>destination_sound.wav</replaceable>. - You may want to normalize the sound before encoding, as DVD audio tracks - are commonly recorded at low volumes. - You can use the tool <application>normalize</application> for instance, - which is available in most distributions. - If you are using Windows, a tool such as <application>BeSweet</application> - can do the same job. - You will compress in either Vorbis or MP3. - For example: - <screen>oggenc -q1 <replaceable>destination_sound.wav</replaceable></screen> - will encode <replaceable>destination_sound.wav</replaceable> with - the encoding quality 1, which is roughly equivalent to 80Kb/s, and - is the minimum quality at which you should encode if you care about - quality. - Please note that <application>MEncoder</application> currently cannot - mux Vorbis audio tracks - into the output file because it only supports AVI and MPEG - containers as an output, each of which may lead to audio/video - playback synchronization problems with some players when the AVI file - contain VBR audio streams such as Vorbis. - Do not worry, this document will show you how you can do that with third - party programs. -</para> - +Audio is a much simpler problem to solve: if you care about quality, just +leave it as is. +Even AC3 5.1 streams are at most 448Kbit/s, and they are worth every bit. +You might be tempted to transcode the audio to high quality Vorbis, but +just because you do not have an A/V receiver for AC3 pass-through today +does not mean you will not have one tomorrow. Future-proof your DVD rips by +preserving the AC3 stream. +You can keep the AC3 stream either by copying it directly into the video +stream <link linkend="menc-feat-mpeg4">during the encoding</link>. +You can also extract the AC3 stream in order to mux it into containers such +as NUT or Matroska. +<screen> +mplayer <replaceable>source_file.vob</replaceable> -aid 129 -dumpaudio -dumpfile <replaceable>sound.ac3</replaceable> +</screen> +will dump into the file <replaceable>sound.ac3</replaceable> the +audio track number 129 from the file +<replaceable>source_file.vob</replaceable> (NB: DVD VOB files +usually use a different audio numbering, +which means that the VOB audio track 129 is the 2nd audio track of the file). +</para> + +<para> +But sometimes you truly have no choice but to further compress the +sound so that more bits can be spent on the video. +Most people choose to compress audio with either MP3 or Vorbis audio codecs. +While the latter is a very space-efficient codec, MP3 is better supported +by hardware players, although this trend is changing. +</para> + +<para> +Do <emphasis>not</emphasis> use <option>-nosound</option> when encoding +a file with audio, even if you will be encoding and muxing audio +separately later. +Though it may work in ideal cases, using <option>-nosound</option> is +likely to hide some problems in your encoding command line setting. +In other words, having a soundtrack during your encode assures you that, +provided you do not see messages such as +<quote>Too many audio packets in the buffer</quote>, you will be able +to get proper sync. +</para> + +<para> +You need to have <application>MEncoder</application> process the sound. +You can for example copy the orignal soundtrack during the encode with +<option>-oac copy</option> or convert it to a "light" 4 kHz mono WAV +PCM with <option>-oac pcm -channels 1 -srate 4000</option>. +Otherwise, in some cases, it will generate a video file that will not sync +with the audio. +Such cases are when the number of video frames in the source file does +not match up to the total length of audio frames or whenever there +are discontinuities/splices where there are missing or extra audio frames. +The correct way to handle this kind of problem is to insert silence or +cut audio at these points. +However <application>MPlayer</application> cannot do that, so if you +demux the AC3 audio and encode it with a separate app (or dump it to PCM with +<application>MPlayer</application>), the splices will be left incorrect +and the only way to correct them is to drop/dup video frames at the +splice. +As long as <application>MEncoder</application> sees the audio when it is +encoding the video, it can do this dropping/duping (which is usually OK +since it takes place at full black/scenechange), but if +<application>MEncoder</application> cannot see the audio, it will just +process all frames as-is and they will not fit the final audio stream when +you for example merge your audio and video track into a Matroska file. +</para> + +<para> +First of all, you will have to convert the DVD sound into a WAV file that the +audio codec can use as input. +For example: +<screen> +mplayer <replaceable>source_file.vob</replaceable> -ao pcm:file=<replaceable>destination_sound.wav</replaceable> \ + -vc dummy -aid 1 -vo null +</screen> +will dump the second audio track from the file +<replaceable>source_file.vob</replaceable> into the file +<replaceable>destination_sound.wav</replaceable>. +You may want to normalize the sound before encoding, as DVD audio tracks +are commonly recorded at low volumes. +You can use the tool <application>normalize</application> for instance, +which is available in most distributions. +If you are using Windows, a tool such as <application>BeSweet</application> +can do the same job. +You will compress in either Vorbis or MP3. +For example: +<screen>oggenc -q1 <replaceable>destination_sound.wav</replaceable></screen> +will encode <replaceable>destination_sound.wav</replaceable> with +the encoding quality 1, which is roughly equivalent to 80Kb/s, and +is the minimum quality at which you should encode if you care about +quality. +Please note that <application>MEncoder</application> currently cannot +mux Vorbis audio tracks +into the output file because it only supports AVI and MPEG +containers as an output, each of which may lead to audio/video +playback synchronization problems with some players when the AVI file +contain VBR audio streams such as Vorbis. +Do not worry, this document will show you how you can do that with third +party programs. +</para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-muxing"> <title>Muxing</title> -<para> - Now that you have encoded your video, you will most likely want - to mux it with one or more audio tracks into a movie container, such - as AVI, MPEG, Matroska or NUT. - <application>MEncoder</application> is currently only able to natively output - audio and video into MPEG and AVI container formats. - for example: - <screen>mencoder -oac copy -ovc copy -o <replaceable>output_movie.avi</replaceable> -audiofile <replaceable>input_audio.mp2</replaceable> <replaceable>input_video.avi</replaceable></screen> - This would merge the video file <replaceable>input_video.avi</replaceable> - and the audio file <replaceable>input_audio.mp2</replaceable> - into the AVI file <replaceable>output_movie.avi</replaceable>. - This command works with MPEG-1 layer I, II and III (more commonly known - as MP3) audio, WAV and a few other audio formats too. -</para> - -<para> - <application>MEncoder</application> features experimental support for - <systemitem class="library">libavformat</systemitem>, which is a - library from the FFmpeg project that supports muxing and demuxing - a variety of containers. - For example: - <screen>mencoder -oac copy -ovc copy -o <replaceable>output_movie.asf</replaceable> -audiofile <replaceable>input_audio.mp2</replaceable> <replaceable>input_video.avi</replaceable> -of lavf -lavfopts format=asf</screen> - This will do the same thing as the previous example, except that - the output container will be ASF. - Please note that this support is highly experimental (but getting - better every day), and will only work if you compiled - <application>MPlayer</application> with the support for - <systemitem class="library">libavformat</systemitem> enabled (which - means that a pre-packaged binary version will not work in most cases). + +<para> +Now that you have encoded your video, you will most likely want +to mux it with one or more audio tracks into a movie container, such +as AVI, MPEG, Matroska or NUT. +<application>MEncoder</application> is currently only able to natively output +audio and video into MPEG and AVI container formats. +for example: +<screen> +mencoder -oac copy -ovc copy -o <replaceable>output_movie.avi</replaceable> \ + -audiofile <replaceable>input_audio.mp2</replaceable> <replaceable>input_video.avi</replaceable> +</screen> +This would merge the video file <replaceable>input_video.avi</replaceable> +and the audio file <replaceable>input_audio.mp2</replaceable> +into the AVI file <replaceable>output_movie.avi</replaceable>. +This command works with MPEG-1 layer I, II and III (more commonly known +as MP3) audio, WAV and a few other audio formats too. +</para> + +<para> +<application>MEncoder</application> features experimental support for +<systemitem class="library">libavformat</systemitem>, which is a +library from the FFmpeg project that supports muxing and demuxing +a variety of containers. +For example: +<screen> +mencoder -oac copy -ovc copy -o <replaceable>output_movie.asf</replaceable> -audiofile <replaceable>input_audio.mp2</replaceable> \ + <replaceable>input_video.avi</replaceable> -of lavf -lavfopts format=asf +</screen> +This will do the same thing as the previous example, except that +the output container will be ASF. +Please note that this support is highly experimental (but getting +better every day), and will only work if you compiled +<application>MPlayer</application> with the support for +<systemitem class="library">libavformat</systemitem> enabled (which +means that a pre-packaged binary version will not work in most cases). </para> <sect3 id="menc-feat-dvd-mpeg4-muxing-filter-issues"> <title>Improving muxing and A/V sync reliability</title> -<para> - You may experience some serious A/V sync problems while trying to mux - your video and some audio tracks, where no matter how you adjust the - audio delay, you will never get proper sync. - That may happen when you use some video filters that will drop or - duplicate some frames, like the inverse telecine filters. - It is strongly encouraged to append the <option>harddup</option> video - filter at the end of the filter chain to avoid this kind of problem. -</para> - -<para> - Without <option>harddup</option>, if <application>MEncoder</application> - wants to duplicate a frame, it relies on the muxer to put a mark on the - container so that the last frame will be displayed again to maintain - sync while writing no actual frame. - With <option>harddup</option>, <application>MEncoder</application> - will instead just push the last frame displayed again into the filter - chain. - This means that the encoder receives the <emphasis>exact</emphasis> - same frame twice, and compresses it. - This will result in a slightly bigger file, but will not cause problems - when demuxing or remuxing into other container formats. -</para> - -<para> - You may also have no choice but to use <option>harddup</option> with - container formats that are not too tightly linked with - <application>MEncoder</application> such as the ones supported through - <systemitem class="library">libavformat</systemitem>, which may not - support frame duplication at the container level. + +<para> +You may experience some serious A/V sync problems while trying to mux +your video and some audio tracks, where no matter how you adjust the +audio delay, you will never get proper sync. +That may happen when you use some video filters that will drop or +duplicate some frames, like the inverse telecine filters. +It is strongly encouraged to append the <option>harddup</option> video +filter at the end of the filter chain to avoid this kind of problem. +</para> + +<para> +Without <option>harddup</option>, if <application>MEncoder</application> +wants to duplicate a frame, it relies on the muxer to put a mark on the +container so that the last frame will be displayed again to maintain +sync while writing no actual frame. +With <option>harddup</option>, <application>MEncoder</application> +will instead just push the last frame displayed again into the filter +chain. +This means that the encoder receives the <emphasis>exact</emphasis> +same frame twice, and compresses it. +This will result in a slightly bigger file, but will not cause problems +when demuxing or remuxing into other container formats. +</para> + +<para> +You may also have no choice but to use <option>harddup</option> with +container formats that are not too tightly linked with +<application>MEncoder</application> such as the ones supported through +<systemitem class="library">libavformat</systemitem>, which may not +support frame duplication at the container level. </para> </sect3> <sect3 id="menc-feat-dvd-mpeg4-muxing-avi-limitations"> <title>Limitations of the AVI container</title> -<para> - Although it is the most widely-supported container format after MPEG-1, - AVI also has some major drawbacks. - Perhaps the most obvious is the overhead. - For each chunk of the AVI file, 24 bytes are wasted on headers and - index. - This translates into a little over 5 MB per hour, or 1-2.5% - overhead for a 700 MB movie. This may not seem like much, but it could - mean the difference between being able to use 700 kbit/sec video or - 714 kbit/sec, and every bit of quality counts. -</para> - -<para> - In addition this gross inefficiency, AVI also has the following major - limitations: + +<para> +Although it is the most widely-supported container format after MPEG-1, +AVI also has some major drawbacks. +Perhaps the most obvious is the overhead. +For each chunk of the AVI file, 24 bytes are wasted on headers and index. +This translates into a little over 5 MB per hour, or 1-2.5% +overhead for a 700 MB movie. This may not seem like much, but it could +mean the difference between being able to use 700 kbit/sec video or +714 kbit/sec, and every bit of quality counts. +</para> + +<para> +In addition this gross inefficiency, AVI also has the following major +limitations: </para> <orderedlist> -<listitem> -<para> +<listitem><para> Only fixed-fps content can be stored. This is particularly limiting if the original material you want to encode is mixed content, for example a mix of NTSC video and film material. Actually there are hacks that can be used to store mixed-framerate content in AVI, but they increase the (already huge) overhead fivefold or more and so are not practical. -</para> -</listitem> -<listitem> -<para> +</para></listitem> +<listitem><para> Audio in AVI files must be either constant-bitrate (CBR) or constant-framesize (i.e. all frames decode to the same number of samples). @@ -1682,164 +1732,168 @@ either of these requirements. Therefore, if you plan to store your movie in AVI, you will have to use a less efficient codec such as MP3 or AC3. -</para> -</listitem> +</para></listitem> </orderedlist> <para> - Having said all that, <application>MEncoder</application> does not - currently support variable-fps output or Vorbis encoding. - Therefore, you may not see these as limitations if - <application>MEncoder</application> is the - only tool you will be using to produce your encodes. - However, it is possible to use <application>MEncoder</application> - only for video encoding, and then use external tools to encode - audio and mux it into another container format. +Having said all that, <application>MEncoder</application> does not +currently support variable-fps output or Vorbis encoding. +Therefore, you may not see these as limitations if +<application>MEncoder</application> is the +only tool you will be using to produce your encodes. +However, it is possible to use <application>MEncoder</application> +only for video encoding, and then use external tools to encode +audio and mux it into another container format. </para> </sect3> + <sect3 id="menc-feat-dvd-mpeg4-muxing-matroska"> <title>Muxing into the Matroska container</title> -<para> - Matroska is a free, open standard container format, aiming - to offer a lot of advanced features, which older containers - like AVI cannot handle. - For example, Matroska supports variable bitrate audio content - (VBR), variable framerates (VFR), chapters, file attachments, - error detection code (EDC) and modern A/V Codecs like "Advanced Audio - Coding" (AAC), "Vorbis" or "MPEG-4 AVC" (H.264), next to nothing - handled by AVI. -</para> - -<para> - The tools required to create Matroska files are collectively called - <application>mkvtoolnix</application>, and are available for most - Unix platforms as well as <application>Windows</application>. - Because Matroska is an open standard you may find other - tools that suit you better, but since mkvtoolnix is the most - common, and is supported by the Matroska team itself, we will - only cover its usage. -</para> - -<para> - Probably the easiest way to get started with Matroska is to use - <application>MMG</application>, the graphical frontend shipped with - <application>mkvtoolnix</application>, and follow the - <ulink url="http://www.bunkus.org/videotools/mkvtoolnix/doc/mkvmerge-gui.html">guide to mkvmerge GUI (mmg)</ulink> -</para> - -<para> - You may also mux audio and video files using the command line: - <screen>mkvmerge -o <replaceable>output.mkv</replaceable> <replaceable>input_video.avi</replaceable> <replaceable>input_audio1.mp3</replaceable> <replaceable>input_audio2.ac3</replaceable></screen> - This would merge the video file <replaceable>input_video.avi</replaceable> - and the two audio files <replaceable>input_audio1.mp3</replaceable> - and <replaceable>input_audio2.ac3</replaceable> into the Matroska - file <replaceable>output.mkv</replaceable>. - Matroska, as mentioned earlier, is able to do much more than that, like - multiple audio tracks (including fine-tuning of audio/video - synchronization), chapters, subtitles, splitting, etc... - Please refer to the documentation of those applications for - more details. -</para> - + +<para> +Matroska is a free, open standard container format, aiming +to offer a lot of advanced features, which older containers +like AVI cannot handle. +For example, Matroska supports variable bitrate audio content +(VBR), variable framerates (VFR), chapters, file attachments, +error detection code (EDC) and modern A/V Codecs like "Advanced Audio +Coding" (AAC), "Vorbis" or "MPEG-4 AVC" (H.264), next to nothing +handled by AVI. +</para> + +<para> +The tools required to create Matroska files are collectively called +<application>mkvtoolnix</application>, and are available for most +Unix platforms as well as <application>Windows</application>. +Because Matroska is an open standard you may find other +tools that suit you better, but since mkvtoolnix is the most +common, and is supported by the Matroska team itself, we will +only cover its usage. +</para> + +<para> +Probably the easiest way to get started with Matroska is to use +<application>MMG</application>, the graphical frontend shipped with +<application>mkvtoolnix</application>, and follow the +<ulink url="http://www.bunkus.org/videotools/mkvtoolnix/doc/mkvmerge-gui.html">guide to mkvmerge GUI (mmg)</ulink> +</para> + +<para> +You may also mux audio and video files using the command line: +<screen> +mkvmerge -o <replaceable>output.mkv</replaceable> <replaceable>input_video.avi</replaceable> <replaceable>input_audio1.mp3</replaceable> <replaceable>input_audio2.ac3</replaceable> +</screen> +This would merge the video file <replaceable>input_video.avi</replaceable> +and the two audio files <replaceable>input_audio1.mp3</replaceable> +and <replaceable>input_audio2.ac3</replaceable> into the Matroska +file <replaceable>output.mkv</replaceable>. +Matroska, as mentioned earlier, is able to do much more than that, like +multiple audio tracks (including fine-tuning of audio/video +synchronization), chapters, subtitles, splitting, etc... +Please refer to the documentation of those applications for +more details. +</para> </sect3> - </sect2> - </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="menc-feat-telecine"> <title>How to deal with telecine and interlacing within NTSC DVDs</title> <sect2 id="menc-feat-telecine-intro"> <title>Introduction</title> + <formalpara> <title>What is telecine?</title> <para> - If you do not understand much of what is written in this document, - read the - <ulink url="http://en.wikipedia.org/wiki/Telecine">Wikipedia entry on telecine</ulink>. - It is an understandable and reasonably comprehensive - description of what telecine is. +If you do not understand much of what is written in this document, read the +<ulink url="http://en.wikipedia.org/wiki/Telecine">Wikipedia entry on telecine</ulink>. +It is an understandable and reasonably comprehensive +description of what telecine is. </para></formalpara> <formalpara> <title>A note about the numbers.</title> <para> - Many documents, including the guide linked above, refer to the fields - per second value of NTSC video as 59.94 and the corresponding frames - per second values as 29.97 (for telecined and interlaced) and 23.976 - (for progressive). For simplicity, some documents even round these - numbers to 60, 30, and 24. +Many documents, including the guide linked above, refer to the fields +per second value of NTSC video as 59.94 and the corresponding frames +per second values as 29.97 (for telecined and interlaced) and 23.976 +(for progressive). For simplicity, some documents even round these +numbers to 60, 30, and 24. </para></formalpara> <para> - Strictly speaking, all those numbers are approximations. Black and - white NTSC video was exactly 60 fields per second, but 60000/1001 - was later chosen to accomodate color data while remaining compatible - with contemporary black and white televisions. Digital NTSC video - (such as on a DVD) is also 60000/1001 fields per second. From this, - interlaced and telecined video are derived to be 30000/1001 frames - per second; progressive video is 24000/1001 frames per second. -</para> - -<para> - Older versions of the <application>MEncoder</application> documentation - and many archived mailing list posts refer to 59.94, 29.97, and 23.976. - All <application>MEncoder</application> documentation has been updated - to use the fractional values, and you should use them too. -</para> - -<para> - <option>-ofps 23.976</option> is incorrect. - <option>-ofps 24000/1001</option> should be used instead. +Strictly speaking, all those numbers are approximations. Black and +white NTSC video was exactly 60 fields per second, but 60000/1001 +was later chosen to accomodate color data while remaining compatible +with contemporary black and white televisions. Digital NTSC video +(such as on a DVD) is also 60000/1001 fields per second. From this, +interlaced and telecined video are derived to be 30000/1001 frames +per second; progressive video is 24000/1001 frames per second. +</para> + +<para> +Older versions of the <application>MEncoder</application> documentation +and many archived mailing list posts refer to 59.94, 29.97, and 23.976. +All <application>MEncoder</application> documentation has been updated +to use the fractional values, and you should use them too. +</para> + +<para> +<option>-ofps 23.976</option> is incorrect. +<option>-ofps 24000/1001</option> should be used instead. </para> <formalpara> <title>How telecine is used.</title> <para> - All video intended to be displayed on an NTSC - television set must be 60000/1001 fields per second. Made-for-TV movies -4 and shows are often filmed directly at 60000/1001 fields per second, but - the majority of cinema is filmed at 24 or 24000/1001 frames per - second. When cinematic movie DVDs are mastered, the video is then - converted for television using a process called telecine. +All video intended to be displayed on an NTSC +television set must be 60000/1001 fields per second. Made-for-TV movies +and shows are often filmed directly at 60000/1001 fields per second, but +the majority of cinema is filmed at 24 or 24000/1001 frames per +second. When cinematic movie DVDs are mastered, the video is then +converted for television using a process called telecine. </para></formalpara> <para> - On a DVD, the video is never actually stored as 60000/1001 fields per - second. For video that was originally 60000/1001, each pair of fields is - combined to form a frame, resulting in 30000/1001 frames per - second. Hardware DVD players then read a flag embedded in the video - stream to determine whether the odd- or even-numbered lines should - form the first field. -</para> - -<para> - Usually, 24000/1001 frames per second content stays as it is when - encoded for a DVD, and the DVD player must perform telecining - on-the-fly. Sometimes, however, the video is telecined - <emphasis>before</emphasis> being stored on the DVD; even though it - was originally 24000/1001 frames per second, it becomes 60000/1001 fields per - second. When it is stored on the DVD, pairs of fields are combined to form - 30000/1001 frames per second. -</para> - -<para> - When looking at individual frames formed from 60000/1001 fields per - second video, telecined or otherwise, interlacing is clearly visible - wherever there is any motion, because one field (say, the - even-numbered lines) represents a moment in time 1/(60000/1001) - seconds later than the other. Playing interlaced video on a computer - looks ugly both because the monitor is higher resolution and because - the video is shown frame-after-frame instead of field-after-field. +On a DVD, the video is never actually stored as 60000/1001 fields per +second. For video that was originally 60000/1001, each pair of fields is +combined to form a frame, resulting in 30000/1001 frames per +second. Hardware DVD players then read a flag embedded in the video +stream to determine whether the odd- or even-numbered lines should +form the first field. +</para> + +<para> +Usually, 24000/1001 frames per second content stays as it is when +encoded for a DVD, and the DVD player must perform telecining +on-the-fly. Sometimes, however, the video is telecined +<emphasis>before</emphasis> being stored on the DVD; even though it +was originally 24000/1001 frames per second, it becomes 60000/1001 fields per +second. When it is stored on the DVD, pairs of fields are combined to form +30000/1001 frames per second. +</para> + +<para> +When looking at individual frames formed from 60000/1001 fields per +second video, telecined or otherwise, interlacing is clearly visible +wherever there is any motion, because one field (say, the +even-numbered lines) represents a moment in time 1/(60000/1001) +seconds later than the other. Playing interlaced video on a computer +looks ugly both because the monitor is higher resolution and because +the video is shown frame-after-frame instead of field-after-field. </para> <itemizedlist> <title>Notes:</title> <listitem><para> This section only applies to NTSC DVDs, and not PAL. - </para></listitem> +</para></listitem> <listitem><para> The example <application>MEncoder</application> lines throughout the document are <emphasis role="bold">not</emphasis> intended for @@ -1847,235 +1901,245 @@ pertaining video category. How to make good DVD rips or fine-tune <systemitem class="library">libavcodec</systemitem> for maximal quality is not within the scope of this document. - </para></listitem> +</para></listitem> <listitem><para> There are a couple footnotes specific to this guide, linked like this: <link linkend="menc-feat-telecine-footnotes">[1]</link> - </para></listitem> +</para></listitem> </itemizedlist> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-telecine-ident"> <title>How to tell what type of video you have</title> <sect3 id="menc-feat-telecine-ident-progressive"> <title>Progressive</title> -<para> - Progressive video was originally filmed at 24000/1001 fps, and stored - on the DVD without alteration. -</para> - -<para> - When you play a progressive DVD in <application>MPlayer</application>, - <application>MPlayer</application> will print the following line as - soon as the movie begins to play: - - <screen> demux_mpg: 24000/1001 fps progressive NTSC content detected, switching framerate.</screen> - - From this point forward, demux_mpg should never say it finds - "30000/1001 fps NTSC content." -</para> - -<para> - When you watch progressive video, you should never see any - interlacing. Beware, however, because sometimes there is a tiny bit - of telecine mixed in where you would not expect. I have encountered TV - show DVDs that have one second of telecine at every scene change, or - at seemingly random places. I once watched a DVD that had a - progressive first half, and the second half was telecined. If you - want to be <emphasis>really</emphasis> thorough, you can scan the - entire movie: - - <screen>mplayer dvd://1 -nosound -vo null -benchmark</screen> - - Using <option>-benchmark</option> makes - <application>MPlayer</application> play the movie as quickly as it - possibly can; still, depending on your hardware, it can take a - while. Every time demux_mpg reports a framerate change, the line - immediately above will show you the time at which the change - occurred. -</para> - -<para> - Sometimes progressive video on DVDs is referred to as - "soft-telecine" because it is intended to - be telecined by the DVD player. + +<para> +Progressive video was originally filmed at 24000/1001 fps, and stored +on the DVD without alteration. +</para> + +<para> +When you play a progressive DVD in <application>MPlayer</application>, +<application>MPlayer</application> will print the following line as +soon as the movie begins to play: +<screen> +demux_mpg: 24000/1001 fps progressive NTSC content detected, switching framerate. +</screen> +From this point forward, demux_mpg should never say it finds +"30000/1001 fps NTSC content." +</para> + +<para> +When you watch progressive video, you should never see any +interlacing. Beware, however, because sometimes there is a tiny bit +of telecine mixed in where you would not expect. I have encountered TV +show DVDs that have one second of telecine at every scene change, or +at seemingly random places. I once watched a DVD that had a +progressive first half, and the second half was telecined. If you +want to be <emphasis>really</emphasis> thorough, you can scan the +entire movie: +<screen>mplayer dvd://1 -nosound -vo null -benchmark</screen> +Using <option>-benchmark</option> makes +<application>MPlayer</application> play the movie as quickly as it +possibly can; still, depending on your hardware, it can take a +while. Every time demux_mpg reports a framerate change, the line +immediately above will show you the time at which the change +occurred. +</para> + +<para> +Sometimes progressive video on DVDs is referred to as +"soft-telecine" because it is intended to +be telecined by the DVD player. </para> </sect3> + <sect3 id="menc-feat-telecine-ident-telecined"> <title>Telecined</title> -<para> - Telecined video was originally filmed at 24000/1001, but was telecined - <emphasis>before</emphasis> it was written to the DVD. -</para> - -<para> - <application>MPlayer</application> does not (ever) report any - framerate changes when it plays telecined video. -</para> - -<para> - Watching a telecined video, you will see interlacing artifacts that - seem to "blink": they repeatedly appear and disappear. - You can look closely at this by - <orderedlist> - <listitem> - <screen>mplayer dvd://1</screen> - </listitem> - <listitem><para> - Seek to a part with motion. - </para></listitem> - <listitem><para> - Use the <keycap>.</keycap> key to step forward one frame at a time. - </para></listitem> - <listitem><para> - Look at the pattern of interlaced-looking and progressive-looking - frames. If the pattern you see is PPPII,PPPII,PPPII,... then the - video is telecined. If you see some other pattern, then the video - may have been telecined using some non-standard method; - <application>MEncoder</application> cannot losslessly convert - non-standard telecine to progressive. If you do not see any - pattern at all, then it is most likely interlaced. - </para></listitem> - </orderedlist> -</para> - -<para> - Sometimes telecined video on DVDs is referred to as - "hard-telecine". Since hard-telecine is already 60000/1001 fields - per second, the DVD player plays the video without any manipulation. -</para> - -<para> - Another way to tell if your source is telecined or not is to play - the source with the <option>-vf pullup</option> and <option>-v</option> - command line options to see how <option>pullup</option> matches frames. - If the source is telecined, you should see on the console a 3:2 pattern - with <systemitem>0+.1.+2</systemitem> and <systemitem>0++1</systemitem> - alternating. - This technique has the advantage that you do not need to watch the - source to identify it, which could be useful if you wish to automate - the encoding procedure, or to carry out said procedure remotely via - a slow connection. -</para> - + +<para> +Telecined video was originally filmed at 24000/1001, but was telecined +<emphasis>before</emphasis> it was written to the DVD. +</para> + +<para> +<application>MPlayer</application> does not (ever) report any +framerate changes when it plays telecined video. +</para> + +<para> +Watching a telecined video, you will see interlacing artifacts that +seem to "blink": they repeatedly appear and disappear. +You can look closely at this by +<orderedlist> +<listitem><screen>mplayer dvd://1</screen></listitem> +<listitem><para> + Seek to a part with motion. +</para></listitem> +<listitem><para> + Use the <keycap>.</keycap> key to step forward one frame at a time. +</para></listitem> +<listitem><para> + Look at the pattern of interlaced-looking and progressive-looking + frames. If the pattern you see is PPPII,PPPII,PPPII,... then the + video is telecined. If you see some other pattern, then the video + may have been telecined using some non-standard method; + <application>MEncoder</application> cannot losslessly convert + non-standard telecine to progressive. If you do not see any + pattern at all, then it is most likely interlaced. +</para></listitem> +</orderedlist> +</para> + +<para> +Sometimes telecined video on DVDs is referred to as +"hard-telecine". Since hard-telecine is already 60000/1001 fields +per second, the DVD player plays the video without any manipulation. +</para> + +<para> +Another way to tell if your source is telecined or not is to play +the source with the <option>-vf pullup</option> and <option>-v</option> +command line options to see how <option>pullup</option> matches frames. +If the source is telecined, you should see on the console a 3:2 pattern +with <systemitem>0+.1.+2</systemitem> and <systemitem>0++1</systemitem> +alternating. +This technique has the advantage that you do not need to watch the +source to identify it, which could be useful if you wish to automate +the encoding procedure, or to carry out said procedure remotely via +a slow connection. +</para> </sect3> + <sect3 id="menc-feat-telecine-ident-interlaced"> <title>Interlaced</title> -<para> - Interlaced video was originally filmed at 60000/1001 fields per second, - and stored on the DVD as 30000/1001 frames per second. The interlacing effect - (often called "combing") is a result of combining pairs of - fields into frames. Each field is supposed to be 1/(60000/1001) seconds apart, - and when they are displayed simultaneously the difference is apparent. -</para> - -<para> - As with telecined video, <application>MPlayer</application> should - not ever report any framerate changes when playing interlaced content. -</para> - -<para> - When you view an interlaced video closely by frame-stepping with the - <keycap>.</keycap> key, you will see that every single frame is interlaced. + +<para> +Interlaced video was originally filmed at 60000/1001 fields per second, +and stored on the DVD as 30000/1001 frames per second. The interlacing effect +(often called "combing") is a result of combining pairs of +fields into frames. Each field is supposed to be 1/(60000/1001) seconds apart, +and when they are displayed simultaneously the difference is apparent. +</para> + +<para> +As with telecined video, <application>MPlayer</application> should +not ever report any framerate changes when playing interlaced content. +</para> + +<para> +When you view an interlaced video closely by frame-stepping with the +<keycap>.</keycap> key, you will see that every single frame is interlaced. </para> </sect3> + <sect3 id="menc-feat-telecine-ident-mixedpt"> <title>Mixed progressive and telecine</title> -<para> - All of a "mixed progressive and telecine" video was originally - 24000/1001 frames per second, but some parts of it ended up being telecined. -</para> - -<para> - When <application>MPlayer</application> plays this category, it will - (often repeatedly) switch back and forth between "30000/1001 fps NTSC" - and "24000/1001 fps progressive NTSC". Watch the bottom of - <application>MPlayer</application>'s output to see these messages. -</para> - -<para> - You should check the "30000/1001 fps NTSC" sections to make sure - they are actually telecine, and not just interlaced. + +<para> +All of a "mixed progressive and telecine" video was originally +24000/1001 frames per second, but some parts of it ended up being telecined. +</para> + +<para> +When <application>MPlayer</application> plays this category, it will +(often repeatedly) switch back and forth between "30000/1001 fps NTSC" +and "24000/1001 fps progressive NTSC". Watch the bottom of +<application>MPlayer</application>'s output to see these messages. +</para> + +<para> +You should check the "30000/1001 fps NTSC" sections to make sure +they are actually telecine, and not just interlaced. </para> </sect3> + <sect3 id="menc-feat-telecine-ident-mixedpi"> <title>Mixed progressive and interlaced</title> -<para> - In "mixed progressive and interlaced" content, progressive - and interlaced video have been spliced together. -</para> - -<para> - This category looks just like "mixed progressive and telecine", - until you examine the 30000/1001 fps sections and see that they do not have the - telecine pattern. + +<para> +In "mixed progressive and interlaced" content, progressive +and interlaced video have been spliced together. +</para> + +<para> +This category looks just like "mixed progressive and telecine", +until you examine the 30000/1001 fps sections and see that they do not have the +telecine pattern. </para> </sect3> - </sect2> +<!-- ********** --> + <sect2 id="menc-feat-telecine-encode"> <title>How to encode each category</title> <para> - As I mentioned in the beginning, example <application>MEncoder</application> - lines below are <emphasis role="bold">not</emphasis> meant to actually be used; - they only demonstrate the minimum parameters to properly encode each category. -</para> +As I mentioned in the beginning, example <application>MEncoder</application> +lines below are <emphasis role="bold">not</emphasis> meant to actually be used; +they only demonstrate the minimum parameters to properly encode each category. +</para> + <sect3 id="menc-feat-telecine-encode-progressive"> <title>Progressive</title> <para> - Progressive video requires no special filtering to encode. The only - parameter you need to be sure to use is - <option>-ofps 24000/1001</option>. Otherwise, <application>MEncoder</application> - will try to encode at 30000/1001 fps and will duplicate frames. -</para> - -<para> - <screen>mencoder dvd://1 -oac copy -ovc lavc -ofps 24000/1001</screen> -</para> - -<para> - It is often the case, however, that a video that looks progressive - actually has very short parts of telecine mixed in. Unless you are - sure, it is safest to treat the video as - <link linkend="menc-feat-telecine-encode-mixedpt">mixed progressive and telecine</link>. - The performance loss is small - <link linkend="menc-feat-telecine-footnotes">[3]</link>. +Progressive video requires no special filtering to encode. The only +parameter you need to be sure to use is <option>-ofps 24000/1001</option>. +Otherwise, <application>MEncoder</application> +will try to encode at 30000/1001 fps and will duplicate frames. +</para> + +<para> +<screen>mencoder dvd://1 -oac copy -ovc lavc -ofps 24000/1001</screen> +</para> + +<para> +It is often the case, however, that a video that looks progressive +actually has very short parts of telecine mixed in. Unless you are +sure, it is safest to treat the video as +<link linkend="menc-feat-telecine-encode-mixedpt">mixed progressive and telecine</link>. +The performance loss is small +<link linkend="menc-feat-telecine-footnotes">[3]</link>. </para> </sect3> + <sect3 id="menc-feat-telecine-encode-telecined"> <title>Telecined</title> -<para> - Telecine can be reversed to retrieve the original 24000/1001 content, - using a process called inverse-telecine. - <application>MPlayer</application> contains several filters to - accomplish this; the best filter, <option>pullup</option>, is described - in the <link linkend="menc-feat-telecine-encode-mixedpt">mixed - progressive and telecine</link> section. + +<para> +Telecine can be reversed to retrieve the original 24000/1001 content, +using a process called inverse-telecine. +<application>MPlayer</application> contains several filters to +accomplish this; the best filter, <option>pullup</option>, is described +in the <link linkend="menc-feat-telecine-encode-mixedpt">mixed +progressive and telecine</link> section. </para> </sect3> + <sect3 id="menc-feat-telecine-encode-interlaced"> <title>Interlaced</title> -<para> - For most practical cases it is not possible to retrieve a complete - progressive video from interlaced content. The only way to do so - without losing half of the vertical resolution is to double the - framerate and try to "guess" what ought to make up the - corresponding lines for each field (this has drawbacks - see method - 3). + +<para> +For most practical cases it is not possible to retrieve a complete +progressive video from interlaced content. The only way to do so +without losing half of the vertical resolution is to double the +framerate and try to "guess" what ought to make up the +corresponding lines for each field (this has drawbacks - see method 3). </para> <orderedlist> <listitem><para> - Encode the video in interlaced form. Normally, interlacing wreaks havoc with the encoder's ability to compress well, but <systemitem class="library">libavcodec</systemitem> has two @@ -2085,9 +2149,8 @@ <link linkend="menc-feat-telecine-footnotes">[2] </link> because it will encode macroblocks as non-interlaced in places where there is no motion. Note that <option>-ofps</option> is NOT needed here. - <screen>mencoder dvd://1 -oac copy -ovc lavc -lavcopts ildct:ilme:mbd=2</screen> - </para></listitem> +</para></listitem> <listitem><para> Use a deinterlacing filter before encoding. There are several of these filters available to choose from, each with its own advantages @@ -2103,9 +2166,8 @@ <option>-ofps</option>. Also, deinterlacing should be done after cropping <link linkend="menc-feat-telecine-footnotes">[1]</link> and before scaling. - <screen>mencoder dvd://1 -oac copy -vf yadif -ovc lavc</screen> - </para></listitem> +</para></listitem> <listitem><para> Unfortunately, this option is buggy with <application>MEncoder</application>; it ought to work well with @@ -2128,9 +2190,11 @@ <emphasis role="bold">have to</emphasis> specify both <option>-fps</option> and <option>-ofps</option> to be twice the framerate of your original source. - - <screen>mencoder dvd://1 -oac copy -vf tfields=2 -ovc lavc -fps 60000/1001 -ofps 60000/1001</screen> - </para></listitem> + <screen> +mencoder dvd://1 -oac copy -vf tfields=2 -ovc lavc \ + -fps 60000/1001 -ofps 60000/1001<!-- + --></screen> +</para></listitem> <listitem><para> If you plan on downscaling dramatically, you can extract and encode only one of the two fields. Of course, you will lose half the vertical @@ -2142,23 +2206,25 @@ appropriately. Remember that you will have to adjust the scale to compensate for the vertical resolution being halved. <screen>mencoder dvd://1 -oac copy -vf field=0 -ovc lavc</screen> - </para></listitem> +</para></listitem> </orderedlist> </sect3> + <sect3 id="menc-feat-telecine-encode-mixedpt"> <title>Mixed progressive and telecine</title> -<para> - In order to turn mixed progressive and telecine video into entirely - progressive video, the telecined parts have to be - inverse-telecined. There are three ways to accomplish this, - described below. Note that you should - <emphasis role="bold">always</emphasis> inverse-telecine before any - rescaling; unless you really know what you are doing, - inverse-telecine before cropping, too - <link linkend="menc-feat-telecine-footnotes">[1]</link>. - <option>-ofps 24000/1001</option> is needed here because the output video - will be 24000/1001 frames per second. + +<para> +In order to turn mixed progressive and telecine video into entirely +progressive video, the telecined parts have to be +inverse-telecined. There are three ways to accomplish this, +described below. Note that you should +<emphasis role="bold">always</emphasis> inverse-telecine before any +rescaling; unless you really know what you are doing, +inverse-telecine before cropping, too +<link linkend="menc-feat-telecine-footnotes">[1]</link>. +<option>-ofps 24000/1001</option> is needed here because the output video +will be 24000/1001 frames per second. </para> <itemizedlist> @@ -2171,13 +2237,12 @@ <option>pullup</option> is, however, the cleanest and most accurate method available for encoding both telecine and "mixed progressive and telecine". - - <screen>mencoder dvd://1 -oac copy -vf pullup,softskip -ovc lavc -ofps 24000/1001</screen> - </para> - - - </listitem> - <listitem><para> + <screen> +mencoder dvd://1 -oac copy -vf pullup,softskip + -ovc lavc -ofps 24000/1001<!-- + --></screen> +</para></listitem> +<listitem><para> An older method is to, rather than inverse-telecine the telecined parts, telecine the non-telecined parts and then inverse-telecine the whole @@ -2186,35 +2251,39 @@ softpulldown with either <option>detc</option> or <option>ivtc</option>, the final result will be entirely progressive. <option>-ofps 24000/1001</option> is needed. - - <screen>mencoder dvd://1 -oac copy -vf softpulldown,ivtc=1 -ovc lavc -ofps 24000/1001</screen> - </para> - </listitem> + <screen> +mencoder dvd://1 -oac copy -vf softpulldown,ivtc=1 -ovc lavc -ofps 24000/1001 + </screen> +</para></listitem> <listitem><para> I have not used <option>-vf filmdint</option> myself, but here is what D Richard Felker III has to say: <blockquote><para>It is OK, but IMO it tries to deinterlace rather - than doing inverse telecine too often (much like settop DVD - players & progressive TVs) which gives ugly flickering and - other artifacts. If you are going to use it, you at least need to - spend some time tuning the options and watching the output first - to make sure it is not messing up.</para></blockquote> - </para></listitem> + than doing inverse telecine too often (much like settop DVD + players & progressive TVs) which gives ugly flickering and + other artifacts. If you are going to use it, you at least need to + spend some time tuning the options and watching the output first + to make sure it is not messing up. + </para></blockquote> +</para></listitem> </itemizedlist> </sect3> + <sect3 id="menc-feat-telecine-encode-mixedpi"> <title>Mixed progressive and interlaced</title> -<para> - There are two options for dealing with this category, each of - which is a compromise. You should decide based on the - duration/location of each type. + +<para> +There are two options for dealing with this category, each of +which is a compromise. You should decide based on the +duration/location of each type. </para> <itemizedlist> -<listitem><para> +<listitem> + <para> Treat it as progressive. The interlaced parts will look interlaced, and some of the interlaced fields will have to be dropped, resulting in a bit of uneven jumpiness. You can use a postprocessing filter if @@ -2251,23 +2320,25 @@ only half progressive, you probably want to encode it as if it is all interlaced. </para> - </listitem> +</listitem> <listitem><para> Treat it as interlaced. Some frames of the progressive parts will need to be duplicated, resulting in uneven jumpiness. Again, deinterlacing filters may slightly degrade the progressive parts. - </para></listitem> - +</para></listitem> </itemizedlist> </sect3> - </sect2> +<!-- ********** --> + <sect2 id="menc-feat-telecine-footnotes"> <title>Footnotes</title> + <orderedlist> -<listitem><formalpara> +<listitem> + <formalpara> <title>About cropping:</title> <para> Video data on DVDs are stored in a format called YUV 4:2:0. In YUV @@ -2311,7 +2382,7 @@ vertically by multiples of four unless you use <option>-vf field</option> before cropping. </para> - </listitem> +</listitem> <listitem><formalpara> <title>About encoding parameters and quality:</title> @@ -2327,8 +2398,7 @@ encoding quality (and decrease encoding speed) but that is beyond the scope of this document. </para> - </formalpara> - </listitem> +</formalpara></listitem> <listitem><formalpara> <title>About the performance of pullup:</title> @@ -2342,16 +2412,15 @@ </option> overshadows that difference, bringing the performance decrease of using <option>pullup</option> down to 2%. </para> - </formalpara> - </listitem> - +</formalpara></listitem> </orderedlist> - </sect2> - </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="menc-feat-enc-libavcodec"> <title>Encoding with the <systemitem class="library">libavcodec</systemitem> codec family</title> @@ -2362,99 +2431,130 @@ You can encode to the following codecs (more or less up to date): </para> +<!-- ********** --> + <sect2 id="menc-feat-enc-libavcodec-video-codecs"> -<title><systemitem class="library">libavcodec</systemitem>'s video codecs</title> +<title><systemitem class="library">libavcodec</systemitem>'s + video codecs</title> <para> <informaltable frame="all"> <tgroup cols="2"> <thead> -<row><entry>Video codec name</entry><entry>Description</entry></row> + <row><entry>Video codec name</entry><entry>Description</entry></row> </thead> <tbody> -<row><entry>mjpeg</entry><entry> - Motion JPEG - </entry></row> -<row><entry>ljpeg</entry><entry> - lossless JPEG - </entry></row> -<row><entry>h261</entry><entry> - H.261 - </entry></row> -<row><entry>h263</entry><entry> - H.263 - </entry></row> -<row><entry>h263p</entry><entry> - H.263+ - </entry></row> -<row><entry>mpeg4</entry><entry> - ISO standard MPEG-4 (DivX, Xvid compatible) - </entry></row> -<row><entry>msmpeg4</entry><entry> - pre-standard MPEG-4 variant by MS, v3 (AKA DivX3) - </entry></row> -<row><entry>msmpeg4v2</entry><entry> - pre-standard MPEG-4 by MS, v2 (used in old ASF files) - </entry></row> -<row><entry>wmv1</entry><entry> - Windows Media Video, version 1 (AKA WMV7) - </entry></row> -<row><entry>wmv2</entry><entry> - Windows Media Video, version 2 (AKA WMV8) - </entry></row> -<row><entry>rv10</entry><entry> - RealVideo 1.0 - </entry></row> -<row><entry>rv20</entry><entry> - RealVideo 2.0 - </entry></row> -<row><entry>mpeg1video</entry><entry> - MPEG-1 video - </entry></row> -<row><entry>mpeg2video</entry><entry> - MPEG-2 video - </entry></row> -<row><entry>huffyuv</entry><entry> - lossless compression - </entry></row> -<row><entry>asv1</entry><entry> - ASUS Video v1 - </entry></row> -<row><entry>asv2</entry><entry> - ASUS Video v2 - </entry></row> -<row><entry>ffv1</entry><entry> - FFmpeg's lossless video codec - </entry></row> -<row><entry>svq1</entry><entry> - Sorenson video 1 - </entry></row> -<row><entry>flv</entry><entry> - Sorenson H.263 used in Flash Video - </entry></row> -<row><entry>dvvideo</entry><entry> - Sony Digital Video - </entry></row> -<row><entry>snow</entry><entry> - FFmpeg's experimental wavelet-based codec - </entry></row> +<row> + <entry>mjpeg</entry> + <entry>Motion JPEG</entry> +</row> +<row> + <entry>ljpeg</entry> + <entry>lossless JPEG</entry> +</row> +<row> + <entry>h261</entry> + <entry>H.261</entry> +</row> +<row> + <entry>h263</entry> + <entry>H.263 </entry> +</row> +<row> + <entry>h263p</entry> + <entry>H.263+</entry> +</row> +<row> + <entry>mpeg4</entry> + <entry>ISO standard MPEG-4 (DivX, Xvid compatible)</entry> +</row> +<row> + <entry>msmpeg4</entry> + <entry>pre-standard MPEG-4 variant by MS, v3 (AKA DivX3)</entry> +</row> +<row> + <entry>msmpeg4v2</entry> + <entry>pre-standard MPEG-4 by MS, v2 (used in old ASF files)</entry> +</row> +<row> + <entry>wmv1</entry> + <entry>Windows Media Video, version 1 (AKA WMV7)</entry> +</row> +<row> + <entry>wmv2</entry> + <entry>Windows Media Video, version 2 (AKA WMV8)</entry> +</row> +<row> + <entry>rv10</entry> + <entry>RealVideo 1.0</entry> +</row> +<row> + <entry>rv20</entry> + <entry>RealVideo 2.0</entry> +</row> +<row> + <entry>mpeg1video</entry> + <entry>MPEG-1 video</entry> +</row> +<row> + <entry>mpeg2video</entry> + <entry>MPEG-2 video</entry> +</row> +<row> + <entry>huffyuv</entry> + <entry>lossless compression</entry> +</row> +<row> + <entry>asv1</entry> + <entry>ASUS Video v1</entry> +</row> +<row> + <entry>asv2</entry> + <entry>ASUS Video v2</entry> +</row> +<row> + <entry>ffv1</entry> + <entry>FFmpeg's lossless video codec</entry> +</row> +<row> + <entry>svq1</entry> + <entry>Sorenson video 1</entry> +</row> +<row> + <entry>flv</entry> + <entry>Sorenson H.263 used in Flash Video</entry> +</row> +<row> + <entry>dvvideo</entry> + <entry>Sony Digital Video</entry> +</row> +<row> + <entry>snow</entry> + <entry>FFmpeg's experimental wavelet-based codec</entry> +</row> </tbody> </tgroup> </informaltable> The first column contains the codec names that should be passed after the -<literal>vcodec</literal> config, like: <option>-lavcopts vcodec=msmpeg4</option> -</para> -<informalexample> -<para> +<literal>vcodec</literal> config, +like: <option>-lavcopts vcodec=msmpeg4</option> +</para> + +<informalexample><para> An example with MJPEG compression: -<screen>mencoder dvd://2 -o title2.avi -ovc lavc -lavcopts vcodec=mjpeg -oac copy</screen> -</para> -</informalexample> +<screen> +mencoder dvd://2 -o <replaceable>title2.avi</replaceable> -ovc lavc -lavcopts vcodec=mjpeg -oac copy +</screen> +</para></informalexample> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-enc-libavcodec-audio-codecs"> -<title><systemitem class="library">libavcodec</systemitem>'s audio codecs</title> +<title><systemitem class="library">libavcodec</systemitem>'s + audio codecs</title> + <para> <informaltable frame="all"> <tgroup cols="2"> @@ -2462,22 +2562,22 @@ <row><entry>Audio codec name</entry><entry>Description</entry></row> </thead> <tbody> - <row> - <entry>mp2</entry> - <entry>MPEG Layer 2</entry> - </row> - <row> - <entry>ac3</entry> - <entry>AC3, AKA Dolby Digital</entry> - </row> - <row> - <entry>adpcm_ima_wav</entry> - <entry>IMA adaptive PCM (4 bits per sample, 4:1 compression)</entry> - </row> - <row> - <entry>sonic</entry> - <entry>experimental lossy/lossless codec</entry> - </row> +<row> + <entry>mp2</entry> + <entry>MPEG Layer 2</entry> +</row> +<row> + <entry>ac3</entry> + <entry>AC3, AKA Dolby Digital</entry> +</row> +<row> + <entry>adpcm_ima_wav</entry> + <entry>IMA adaptive PCM (4 bits per sample, 4:1 compression)</entry> +</row> +<row> + <entry>sonic</entry> + <entry>experimental lossy/lossless codec</entry> +</row> </tbody> </tgroup> </informaltable> @@ -2486,43 +2586,43 @@ <literal>acodec</literal> option, like: <option>-lavcopts acodec=ac3</option> </para> -<informalexample> -<para> +<informalexample><para> An example with AC3 compression: -<screen>mencoder dvd://2 -o title2.avi -oac lavc -lavcopts acodec=ac3 -ovc copy</screen> -</para> -</informalexample> - -<para> - Contrary to <systemitem class="library">libavcodec</systemitem>'s video - codecs, its audio codecs do not make a wise usage of the bits they are - given as they lack some minimal psychoacoustic model (if at all) - which most other codec implementations feature. - However, note that all these audio codecs are very fast and work - out-of-the-box everywhere <application>MEncoder</application> has been - compiled with <systemitem class="library">libavcodec</systemitem> (which - is the case most of time), and do not depend on external libraries. +<screen> +mencoder dvd://2 -o <replaceable>title2.avi</replaceable> -oac lavc -lavcopts acodec=ac3 -ovc copy +</screen> +</para></informalexample> + +<para> +Contrary to <systemitem class="library">libavcodec</systemitem>'s video +codecs, its audio codecs do not make a wise usage of the bits they are +given as they lack some minimal psychoacoustic model (if at all) +which most other codec implementations feature. +However, note that all these audio codecs are very fast and work +out-of-the-box everywhere <application>MEncoder</application> has been +compiled with <systemitem class="library">libavcodec</systemitem> (which +is the case most of time), and do not depend on external libraries. </para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-lavc-encoding-options"> <title>Encoding options of libavcodec</title> <para> - Ideally, you would probably want to be able to just tell the encoder to switch - into "high quality" mode and move on. - That would probably be nice, but unfortunately hard to implement as different - encoding options yield different quality results depending on the source material. - That is because compression depends on the visual properties of the video - in question. - For example, anime and live action have very different properties and - thus require different options to obtain optimum encoding. - The good news is that some options should never be left out, like - <option>mbd=2</option>, <option>trell</option>, and <option>v4mv</option>. - See below for a detailed description of common encoding options. -</para> - +Ideally, you would probably want to be able to just tell the encoder to switch +into "high quality" mode and move on. +That would probably be nice, but unfortunately hard to implement as different +encoding options yield different quality results depending on the source +material. That is because compression depends on the visual properties of the +video in question. +For example, anime and live action have very different properties and +thus require different options to obtain optimum encoding. +The good news is that some options should never be left out, like +<option>mbd=2</option>, <option>trell</option>, and <option>v4mv</option>. +See below for a detailed description of common encoding options. +</para> <itemizedlist> <title>Options to adjust:</title> @@ -2535,26 +2635,22 @@ option, but you need to deactivate scene detection, which is not a good idea as it will hurt encode efficiency a bit. </para></listitem> - <listitem><para> <emphasis role="bold">vb_strategy=1</emphasis>: helps in high-motion scenes. On some videos, vmax_b_frames may hurt quality, but vmax_b_frames=2 along with vb_strategy=1 helps. </para></listitem> - <listitem><para> <emphasis role="bold">dia</emphasis>: motion search range. Bigger is better and slower. Negative values are a completely different scale. Good values are -1 for a fast encode, or 2-4 for slower. </para></listitem> - <listitem><para> <emphasis role="bold">predia</emphasis>: motion search pre-pass. Not as important as dia. Good values are 1 (default) to 4. Requires preme=2 to really be useful. </para></listitem> - <listitem><para> <emphasis role="bold">cmp, subcmp, precmp</emphasis>: Comparison function for motion estimation. @@ -2564,19 +2660,16 @@ For cmp and subcmp, 2 is good for anime, and 3 is good for live action. 6 may or may not be slightly better, but is slow. </para></listitem> - <listitem><para> <emphasis role="bold">last_pred</emphasis>: Number of motion predictors to take from the previous frame. 1-3 or so help at little speed cost. Higher values are slow for no extra gain. </para></listitem> - <listitem><para> - <emphasis role="bold">cbp, mv0</emphasis>: Controls the selection of macroblocks. - Small speed cost for small quality gain. + <emphasis role="bold">cbp, mv0</emphasis>: Controls the selection of + macroblocks. Small speed cost for small quality gain. </para></listitem> - <listitem><para> <emphasis role="bold">qprd</emphasis>: adaptive quantization based on the macroblock's complexity. @@ -2584,7 +2677,6 @@ This can cause artifacts unless you set vqmax to some reasonably small value (6 is good, maybe as low as 4); vqmin=1 should also help. </para></listitem> - <listitem><para> <emphasis role="bold">qns</emphasis>: very slow, especially when combined with qprd. @@ -2593,7 +2685,6 @@ Do not use this unless you have already tweaked everything else as far as it will go and the results still are not good enough. </para></listitem> - <listitem><para> <emphasis role="bold">vqcomp</emphasis>: Tweak ratecontrol. What values are good depends on the movie. @@ -2602,7 +2693,6 @@ them on high-complexity scenes (default: 0.5, range: 0-1. recommended range: 0.5-0.7). </para></listitem> - <listitem><para> <emphasis role="bold">vlelim, vcelim</emphasis>: Sets the single coefficient elimination threshold for luminance and chroma planes. @@ -2614,7 +2704,6 @@ seem to be good for live movies, but seem not to help with anime; when encoding animation, you should probably leave them unchanged. </para></listitem> - <listitem><para> <emphasis role="bold">qpel</emphasis>: Quarter pixel motion estimation. MPEG-4 uses half pixel precision for its motion search by default, @@ -2625,13 +2714,11 @@ qpel always incurs a significant cost in CPU decode time (+25% in practice). </para></listitem> - <listitem><para> <emphasis role="bold">psnr</emphasis>: does not affect the actual encoding, but writes a log file giving the type/size/quality of each frame, and prints a summary of PSNR (Peak Signal to Noise Ratio) at the end. </para></listitem> - </itemizedlist> <itemizedlist> @@ -2639,7 +2726,6 @@ <listitem><para> <emphasis role="bold">vme</emphasis>: The default is best. </para></listitem> - <listitem><para> <emphasis role="bold">lumi_mask, dark_mask</emphasis>: Psychovisual adaptive quantization. @@ -2647,7 +2733,6 @@ Reasonable values may be effective in your case, but be warned this is very subjective. </para></listitem> - <listitem><para> <emphasis role="bold">scplx_mask</emphasis>: Tries to prevent blocky artifacts, but postprocessing is better. @@ -2655,31 +2740,38 @@ </itemizedlist> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-mpeg4-lavc-example-settings"> <title>Encoding setting examples</title> <para> - The following settings are examples of different encoding - option combinations that affect the speed vs quality tradeoff - at the same target bitrate. -</para> - -<para> - All the encoding settings were tested on a 720x448 @30000/1001 fps - video sample, the target bitrate was 900kbps, and the machine was an - AMD-64 3400+ at 2400 MHz in 64 bits mode. - Each encoding setting features the measured encoding speed (in - frames per second) and the PSNR loss (in dB) compared to the "very - high quality" setting. - Please understand that depending on your source, your machine type - and development advancements, you may get very different results. +The following settings are examples of different encoding +option combinations that affect the speed vs quality tradeoff +at the same target bitrate. +</para> + +<para> +All the encoding settings were tested on a 720x448 @30000/1001 fps +video sample, the target bitrate was 900kbps, and the machine was an +AMD-64 3400+ at 2400 MHz in 64 bits mode. +Each encoding setting features the measured encoding speed (in +frames per second) and the PSNR loss (in dB) compared to the "very +high quality" setting. +Please understand that depending on your source, your machine type +and development advancements, you may get very different results. </para> <para> <informaltable frame="all"> <tgroup cols="4"> <thead> -<row><entry>Description</entry><entry>Encoding options</entry><entry>speed (in fps)</entry><entry>Relative PSNR loss (in dB)</entry></row> +<row> + <entry>Description</entry> + <entry>Encoding options</entry> + <entry>speed (in fps)</entry> + <entry>Relative PSNR loss (in dB)</entry> +</row> </thead> <tbody> <row> @@ -2712,7 +2804,10 @@ </para> </sect2> -<sect2 id="custommatrices"><title>Custom inter/intra matrices</title> +<!-- ********** --> + +<sect2 id="custommatrices"> +<title>Custom inter/intra matrices</title> <para> With this feature of @@ -2761,202 +2856,204 @@ <para> Usage: <screen> -$ mencoder <replaceable>input.avi</replaceable> -o <replaceable>output.avi</replaceable> -oac copy -ovc lavc -lavcopts inter_matrix=...:intra_matrix=... +mencoder <replaceable>input.avi</replaceable> -o <replaceable>output.avi</replaceable> -oac copy -ovc lavc \ + -lavcopts inter_matrix=...:intra_matrix=... </screen> </para> <para> <screen> -$ mencoder <replaceable>input.avi</replaceable> -ovc lavc -lavcopts -vcodec=mpeg2video:intra_matrix=8,9,12,22,26,27,29,34,9,10,14,26,27,29,34,37, -12,14,18,27,29,34,37,38,22,26,27,31,36,37,38,40,26,27,29,36,39,38,40,48,27, -29,34,37,38,40,48,58,29,34,37,38,40,48,58,69,34,37,38,40,48,58,69,79 -:inter_matrix=16,18,20,22,24,26,28,30,18,20,22,24,26,28,30,32,20,22,24,26, -28,30,32,34,22,24,26,30,32,32,34,36,24,26,28,32,34,34,36,38,26,28,30,32,34, +mencoder <replaceable>input.avi</replaceable> -ovc lavc -lavcopts \ +vcodec=mpeg2video:intra_matrix=8,9,12,22,26,27,29,34,9,10,14,26,27,29,34,37,\ +12,14,18,27,29,34,37,38,22,26,27,31,36,37,38,40,26,27,29,36,39,38,40,48,27,\ +29,34,37,38,40,48,58,29,34,37,38,40,48,58,69,34,37,38,40,48,58,69,79\ +:inter_matrix=16,18,20,22,24,26,28,30,18,20,22,24,26,28,30,32,20,22,24,26,\ +28,30,32,34,22,24,26,30,32,32,34,36,24,26,28,32,34,34,36,38,26,28,30,32,34,\ 36,38,40,28,30,32,34,36,38,42,42,30,32,34,36,38,40,42,44 -oac copy -o svcd.mpg </screen> </para> </sect2> +<!-- ********** --> <sect2 id="menc-feat-dvd-mpeg4-example"> <title>Example</title> <para> - So, you have just bought your shiny new copy of Harry Potter and the Chamber - of Secrets (widescreen edition, of course), and you want to rip this DVD - so that you can add it to your Home Theatre PC. This is a region 1 DVD, - so it is NTSC. The example below will still apply to PAL, except you will - omit <option>-ofps 24000/1001</option> (because the output framerate is the - same as the input framerate), and of course the crop dimensions will be - different. -</para> - -<para> - After running <option>mplayer dvd://1</option>, we follow the process - detailed in the section <link linkend="menc-feat-telecine">How to deal - with telecine and interlacing in NTSC DVDs</link> and discover that it is - 24000/1001 fps progressive video, which means that we need not use an inverse - telecine filter, such as <option>pullup</option> or - <option>filmdint</option>. -</para> - -<para> - Next, we want to determine the appropriate crop rectangle, so we use the - cropdetect filter: - - <screen>mplayer dvd://1 -vf cropdetect</screen> - - Make sure you seek to a fully filled frame (such as a bright scene), and - you will see in <application>MPlayer</application>'s console output: - - <screen>crop area: X: 0..719 Y: 57..419 (-vf crop=720:362:0:58)</screen> - - We then play the movie back with this filter to test its correctness: - - <screen>mplayer dvd://1 -vf crop=720:362:0:58</screen> - - And we see that it looks perfectly fine. Next, we ensure the width and - height are a multiple of 16. The width is fine, however the height is - not. Since we did not fail 7th grade math, we know that the nearest - multiple of 16 lower than 362 is 352. -</para> - -<para> - We could just use <option>crop=720:352:0:58</option>, but it would be nice - to take a little off the top and a little off the bottom so that we - retain the center. We have shrunk the height by 10 pixels, but we do not - want to increase the y-offset by 5-pixels since that is an odd number and - will adversely affect quality. Instead, we will increase the y-offset by - 4 pixels: - - <screen>mplayer dvd://1 -vf crop=720:352:0:62</screen> - - Another reason to shave pixels from both the top and the bottom is that we - ensure we have eliminated any half-black pixels if they exist. Note that if - your video is telecined, make sure the <option>pullup</option> filter (or - whichever inverse telecine filter you decide to use) appears in the filter - chain before you crop. If it is interlaced, deinterlace before cropping. - (If you choose to preserve the interlaced video, then make sure your - vertical crop offset is a multiple of 4.) -</para> - -<para> - If you are really concerned about losing those 10 pixels, you might - prefer instead to scale the dimensions down to the nearest multiple of 16. - The filter chain would look like: - - <screen>-vf crop=720:362:0:58,scale=720:352</screen> - - Scaling the video down like this will mean that some small amount of - detail is lost, though it probably will not be perceptible. Scaling up will - result in lower quality (unless you increase the bitrate). Cropping - discards those pixels altogether. It is a tradeoff that you will want to - consider for each circumstance. For example, if the DVD video was made - for television, you might want to avoid vertical scaling, since the line - sampling corresponds to the way the content was originally recorded. -</para> - -<para> - On inspection, we see that our movie has a fair bit of action and high - amounts of detail, so we pick 2400Kbit for our bitrate. -</para> - -<para> - We are now ready to do the two pass encode. Pass one: - - <screen>mencoder dvd://1 -ofps 24000/1001 -oac copy -vf pullup,softskip,crop=720:352:0:62,hqdn3d=2:1:2 -ovc lavc \ --lavcopts vcodec=mpeg4:vbitrate=2400:v4mv:mbd=2:trell:cmp=3:subcmp=3:mbcmp=3:autoaspect:vpass=1 \ --o Harry_Potter_2.avi</screen> - - And pass two is the same, except that we specify <option>vpass=2</option>: - - <screen>mencoder dvd://1 -ofps 24000/1001 -oac copy -vf pullup,softskip,crop=720:352:0:62,hqdn3d=2:1:2 -ovc lavc \ --lavcopts vcodec=mpeg4:vbitrate=2400:v4mv:mbd=2:trell:cmp=3:subcmp=3:mbcmp=3:autoaspect:vpass=2 \ --o Harry_Potter_2.avi</screen> -</para> - -<para> - The options <option>v4mv:mbd=2:trell</option> will greatly increase the - quality at the expense of encoding time. There is little reason to leave - these options out when the primary goal is quality. The options - <option>cmp=3:subcmp=3:mbcmp=3</option> select a comparison function that - yields higher quality than the defaults. You might try experimenting with - this parameter (refer to the man page for the possible values) as - different functions can have a large impact on quality depending on the - source material. For example, if you find - <systemitem class="library">libavcodec</systemitem> produces too much - blocky artifacting, you could try selecting the experimental NSSE as - comparison function via <option>*cmp=10</option>. -</para> - -<para> - For this movie, the resulting AVI will be 138 minutes long and nearly - 3GB. And because you said that file size does not matter, this is a - perfectly acceptable size. However, if you had wanted it smaller, you - could try a lower bitrate. Increasing bitrates have diminishing - returns, so while we might clearly see an improvement from 1800Kbit to - 2000Kbit, it might not be so noticeable above 2000Kbit. Feel - free to experiment until you are happy. -</para> - -<para> - Because we passed the source video through a denoise filter, you may want - to add some of it back during playback. This, along with the - <option>spp</option> post-processing filter, drastically improves the - perception of quality and helps eliminate blocky artifacts in the video. - With <application>MPlayer</application>'s <option>autoq</option> option, - you can vary the amount of post-processing done by the spp filter - depending on available CPU. Also, at this point, you may want to apply - gamma and/or color correction to best suit your display. For example: - - <screen>mplayer Harry_Potter_2.avi -vf spp,noise=9ah:5ah,eq2=1.2 -autoq 3</screen> - +So, you have just bought your shiny new copy of Harry Potter and the Chamber +of Secrets (widescreen edition, of course), and you want to rip this DVD +so that you can add it to your Home Theatre PC. This is a region 1 DVD, +so it is NTSC. The example below will still apply to PAL, except you will +omit <option>-ofps 24000/1001</option> (because the output framerate is the +same as the input framerate), and of course the crop dimensions will be +different. +</para> + +<para> +After running <option>mplayer dvd://1</option>, we follow the process +detailed in the section <link linkend="menc-feat-telecine">How to deal +with telecine and interlacing in NTSC DVDs</link> and discover that it is +24000/1001 fps progressive video, which means that we need not use an inverse +telecine filter, such as <option>pullup</option> or +<option>filmdint</option>. +</para> + +<para> +Next, we want to determine the appropriate crop rectangle, so we use the +cropdetect filter: +<screen>mplayer dvd://1 -vf cropdetect</screen> +Make sure you seek to a fully filled frame (such as a bright scene), and +you will see in <application>MPlayer</application>'s console output: +<screen>crop area: X: 0..719 Y: 57..419 (-vf crop=720:362:0:58)</screen> +We then play the movie back with this filter to test its correctness: +<screen>mplayer dvd://1 -vf crop=720:362:0:58</screen> +And we see that it looks perfectly fine. Next, we ensure the width and +height are a multiple of 16. The width is fine, however the height is +not. Since we did not fail 7th grade math, we know that the nearest +multiple of 16 lower than 362 is 352. +</para> + +<para> +We could just use <option>crop=720:352:0:58</option>, but it would be nice +to take a little off the top and a little off the bottom so that we +retain the center. We have shrunk the height by 10 pixels, but we do not +want to increase the y-offset by 5-pixels since that is an odd number and +will adversely affect quality. Instead, we will increase the y-offset by +4 pixels: +<screen>mplayer dvd://1 -vf crop=720:352:0:62</screen> +Another reason to shave pixels from both the top and the bottom is that we +ensure we have eliminated any half-black pixels if they exist. Note that if +your video is telecined, make sure the <option>pullup</option> filter (or +whichever inverse telecine filter you decide to use) appears in the filter +chain before you crop. If it is interlaced, deinterlace before cropping. +(If you choose to preserve the interlaced video, then make sure your +vertical crop offset is a multiple of 4.) +</para> + +<para> +If you are really concerned about losing those 10 pixels, you might +prefer instead to scale the dimensions down to the nearest multiple of 16. +The filter chain would look like: +<screen>-vf crop=720:362:0:58,scale=720:352</screen> +Scaling the video down like this will mean that some small amount of +detail is lost, though it probably will not be perceptible. Scaling up will +result in lower quality (unless you increase the bitrate). Cropping +discards those pixels altogether. It is a tradeoff that you will want to +consider for each circumstance. For example, if the DVD video was made +for television, you might want to avoid vertical scaling, since the line +sampling corresponds to the way the content was originally recorded. +</para> + +<para> +On inspection, we see that our movie has a fair bit of action and high +amounts of detail, so we pick 2400Kbit for our bitrate. +</para> + +<para> +We are now ready to do the two pass encode. Pass one: +<screen> +mencoder dvd://1 -ofps 24000/1001 -oac copy -o <replaceable>Harry_Potter_2.avi</replaceable> -ovc lavc \ + -lavcopts vcodec=mpeg4:vbitrate=2400:v4mv:mbd=2:trell:cmp=3:subcmp=3:mbcmp=3:autoaspect:vpass=1 \ + -vf pullup,softskip,crop=720:352:0:62,hqdn3d=2:1:2 +</screen> +And pass two is the same, except that we specify <option>vpass=2</option>: +<screen> +mencoder dvd://1 -ofps 24000/1001 -oac copy -o <replaceable>Harry_Potter_2.avi</replaceable> -ovc lavc \ + -lavcopts vcodec=mpeg4:vbitrate=2400:v4mv:mbd=2:trell:cmp=3:subcmp=3:mbcmp=3:autoaspect:vpass=2 \ + -vf pullup,softskip,crop=720:352:0:62,hqdn3d=2:1:2 +</screen> +</para> + +<para> +The options <option>v4mv:mbd=2:trell</option> will greatly increase the +quality at the expense of encoding time. There is little reason to leave +these options out when the primary goal is quality. The options +<option>cmp=3:subcmp=3:mbcmp=3</option> select a comparison function that +yields higher quality than the defaults. You might try experimenting with +this parameter (refer to the man page for the possible values) as +different functions can have a large impact on quality depending on the +source material. For example, if you find +<systemitem class="library">libavcodec</systemitem> produces too much +blocky artifacting, you could try selecting the experimental NSSE as +comparison function via <option>*cmp=10</option>. +</para> + +<para> +For this movie, the resulting AVI will be 138 minutes long and nearly +3GB. And because you said that file size does not matter, this is a +perfectly acceptable size. However, if you had wanted it smaller, you +could try a lower bitrate. Increasing bitrates have diminishing +returns, so while we might clearly see an improvement from 1800Kbit to +2000Kbit, it might not be so noticeable above 2000Kbit. Feel +free to experiment until you are happy. +</para> + +<para> +Because we passed the source video through a denoise filter, you may want +to add some of it back during playback. This, along with the +<option>spp</option> post-processing filter, drastically improves the +perception of quality and helps eliminate blocky artifacts in the video. +With <application>MPlayer</application>'s <option>autoq</option> option, +you can vary the amount of post-processing done by the spp filter +depending on available CPU. Also, at this point, you may want to apply +gamma and/or color correction to best suit your display. For example: +<screen> +mplayer <replaceable>Harry_Potter_2.avi</replaceable> -vf spp,noise=9ah:5ah,eq2=1.2 -autoq 3 +</screen> </para> </sect2> </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="menc-feat-xvid"> <title>Encoding with the <systemitem class="library">Xvid</systemitem> -codec</title> -<para> - <systemitem class="library">Xvid</systemitem> is a free library for - encoding MPEG-4 ASP video streams. - Before starting to encode, you need to <link linkend="xvid"> - set up <application>MEncoder</application> to support it</link>. -</para> -<para> - This guide mainly aims at featuring the same kind of information - as x264's encoding guide. - Therefore, please begin by reading - <link linkend="menc-feat-x264-encoding-options-intro">the first part</link> - of that guide. -</para> - + codec</title> + +<para> +<systemitem class="library">Xvid</systemitem> is a free library for +encoding MPEG-4 ASP video streams. +Before starting to encode, you need to <link linkend="xvid"> +set up <application>MEncoder</application> to support it</link>. +</para> + +<para> +This guide mainly aims at featuring the same kind of information +as x264's encoding guide. +Therefore, please begin by reading +<link linkend="menc-feat-x264-encoding-options-intro">the first part</link> +of that guide. +</para> + +<!-- ********** --> <sect2 id="menc-feat-xvid-intro"> <title>What options should I use to get the best results?</title> <para> - Please begin by reviewing the - <systemitem class="library">Xvid</systemitem> section of - <application>MPlayer</application>'s man page. - This section is intended to be a supplement to the man page. -</para> -<para> - The Xvid default settings are already a good tradeoff between - speed and quality, therefore you can safely stick to them if - the following section puzzles you. +Please begin by reviewing the +<systemitem class="library">Xvid</systemitem> section of +<application>MPlayer</application>'s man page. +This section is intended to be a supplement to the man page. +</para> + +<para> +The Xvid default settings are already a good tradeoff between +speed and quality, therefore you can safely stick to them if +the following section puzzles you. </para> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-xvid-encoding-options"> <title>Encoding options of <systemitem class="library">Xvid</systemitem></title> <itemizedlist> <listitem><para> - <emphasis role="bold">vhq</emphasis> + <emphasis role="bold">vhq</emphasis> This setting affects the macroblock decision algorithm, where the higher the setting, the wiser the decision. The default setting may be safely used for every encode, while @@ -2967,16 +3064,14 @@ Turning it off will noticeably speed up encoding; if speed is critical for you, the tradeoff may be worth it. </para></listitem> - <listitem><para> - <emphasis role="bold">bvhq</emphasis> + <emphasis role="bold">bvhq</emphasis> This does the same job as vhq, but does it on B-frames. It has a negligible impact on speed, and slightly improves quality (around +0.1dB PSNR). </para></listitem> - <listitem><para> - <emphasis role="bold">max_bframes</emphasis> + <emphasis role="bold">max_bframes</emphasis> A higher number of consecutive allowed B-frames usually improves compressibility, although it may also lead to more blocking artifacts. The default setting is a good tradeoff between compressibility and @@ -2986,9 +3081,8 @@ target bitrate is high enough to ensure that the encoder does not have to increase quantizers to reach it. </para></listitem> - <listitem><para> - <emphasis role="bold">bf_threshold</emphasis> + <emphasis role="bold">bf_threshold</emphasis> This controls the B-frame sensitivity of the encoder, where a higher value leads to more B-frames being used (and vice versa). This setting is to be used together with <option>max_bframes</option>; @@ -3007,9 +3101,8 @@ consecutive B-frame), this would be your only way to increase compressibility through using B-frames. </para></listitem> - <listitem><para> - <emphasis role="bold">trellis</emphasis> + <emphasis role="bold">trellis</emphasis> Optimizes the quantization process to get an optimal tradeoff between PSNR and bitrate, which allows significant bit saving. These bits will in return be spent elsewhere on the video, @@ -3019,7 +3112,6 @@ have turned down <option>vhq</option> and all other more CPU-hungry options to the minimum. </para></listitem> - <listitem><para> <emphasis role="bold">hq_ac</emphasis> Activates a better coefficient cost estimation method, which slightly @@ -3027,32 +3119,31 @@ than 0.01dB PSNR increase), while having a negligible impact on speed. It is therefore recommended to always leave it on. </para></listitem> - <listitem><para> <emphasis role="bold">cartoon</emphasis> Designed to better encode cartoon content, and has no impact on speed as it just tunes the mode decision heuristics for this type of content. </para></listitem> - -<listitem><para> - <emphasis role="bold">me_quality</emphasis> +<listitem> + <para> + <emphasis role="bold">me_quality</emphasis> This setting is to control the precision of the motion estimation. The higher <option>me_quality</option>, the more precise the estimation of the original motion will be, and the better the resulting clip will capture the original motion. - </para> - <para> + </para> + <para> The default setting is best in all cases; thus it is not recommended to turn it down unless you are really looking for speed, as all the bits saved by a good motion estimation would be spent elsewhere, raising overall quality. Therefore, do not go any lower than 5, and even that only as a last resort. -</para></listitem> - + </para> +</listitem> <listitem><para> - <emphasis role="bold">chroma_me</emphasis> + <emphasis role="bold">chroma_me</emphasis> Improves motion estimation by also taking the chroma (color) information into account, whereas <option>me_quality</option> alone only uses luma (grayscale). @@ -3062,73 +3153,75 @@ If you are looking for speed, you should disable this option before starting to consider reducing <option>me_quality</option>. </para></listitem> - <listitem><para> <emphasis role="bold">chroma_opt</emphasis> - Is intended to increase chroma image quality around pure - white/black edges, rather than improving compression. - This can help to reduce the "red stairs" effect. + Is intended to increase chroma image quality around pure + white/black edges, rather than improving compression. + This can help to reduce the "red stairs" effect. </para></listitem> - <listitem><para> <emphasis role="bold">lumi_mask</emphasis> - Tries to give less bitrate to part of the picture that the - human eye cannot see very well, which should allow the encoder - to spend the saved bits on more important parts of the picture. - The quality of the encode yielded by this option highly depends - on personal preferences and on the type and monitor settings - used to watch it (typically, it will not look as good if it is - bright or if it is a TFT monitor). + Tries to give less bitrate to part of the picture that the + human eye cannot see very well, which should allow the encoder + to spend the saved bits on more important parts of the picture. + The quality of the encode yielded by this option highly depends + on personal preferences and on the type and monitor settings + used to watch it (typically, it will not look as good if it is + bright or if it is a TFT monitor). </para></listitem> - -<listitem><para> +<listitem> + <para> <emphasis role="bold">qpel</emphasis> - Raise the number of candidate motion vectors by increasing - the precision of the motion estimation from halfpel to - quarterpel. - The idea is to find better motion vectors which will in return - reduce bitrate (hence increasing quality). - However, motion vectors with quarterpel precision require a - few extra bits to code, but the candidate vectors do not always - give (much) better results. - Quite often, the codec still spends bits on the extra precision, - but little or no extra quality is gained in return. - Unfortunately, there is no way to foresee the possible gains of - <option>qpel</option>, so you need to actually encode with and - without it to know for sure. - </para><para> - <option>qpel</option> can be almost double encoding time, and - requires as much as 25% more processing power to decode. - It is not supported by all standalone players. -</para></listitem> - + Raise the number of candidate motion vectors by increasing + the precision of the motion estimation from halfpel to + quarterpel. + The idea is to find better motion vectors which will in return + reduce bitrate (hence increasing quality). + However, motion vectors with quarterpel precision require a + few extra bits to code, but the candidate vectors do not always + give (much) better results. + Quite often, the codec still spends bits on the extra precision, + but little or no extra quality is gained in return. + Unfortunately, there is no way to foresee the possible gains of + <option>qpel</option>, so you need to actually encode with and + without it to know for sure. + </para> + <para> + <option>qpel</option> can be almost double encoding time, and + requires as much as 25% more processing power to decode. + It is not supported by all standalone players. + </para> +</listitem> <listitem><para> <emphasis role="bold">gmc</emphasis> - Tries to save bits on panning scenes by using a single motion - vector for the whole frame. - This almost always raises PSNR, but significantly slows down - encoding (as well as decoding). - Therefore, you should only use it when you have turned - <option>vhq</option> to the maximum. - <systemitem class="library">Xvid</systemitem>'s GMC is more - sophisticated than DivX's, but is only supported by few - standalone players. + Tries to save bits on panning scenes by using a single motion + vector for the whole frame. + This almost always raises PSNR, but significantly slows down + encoding (as well as decoding). + Therefore, you should only use it when you have turned + <option>vhq</option> to the maximum. + <systemitem class="library">Xvid</systemitem>'s GMC is more + sophisticated than DivX's, but is only supported by few + standalone players. </para></listitem> - </itemizedlist> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-xvid-encoding-profiles"> <title>Encoding profiles</title> -<para> - Xvid supports encoding profiles through the <option>profile</option> option, - which are used to impose restrictions on the properties of the Xvid video - stream such that it will be playable on anything which supports the - chosen profile. - The restrictions relate to resolutions, bitrates and certain MPEG-4 - features. - The following table shows what each profile supports. -</para> + +<para> +Xvid supports encoding profiles through the <option>profile</option> option, +which are used to impose restrictions on the properties of the Xvid video +stream such that it will be playable on anything which supports the +chosen profile. +The restrictions relate to resolutions, bitrates and certain MPEG-4 +features. +The following table shows what each profile supports. +</para> + <informaltable> <tgroup cols="16" align="center"> <colspec colnum="1" colname="col1"/> @@ -3151,267 +3244,268 @@ <spanspec spanname="spa2-5" namest="col2" nameend="col5"/> <spanspec spanname="spa6-11" namest="col6" nameend="col11"/> <spanspec spanname="spa12-17" namest="col12" nameend="col17"/> - <tbody> - <row> - <entry></entry> - <entry spanname="spa2-5">Simple</entry> - <entry spanname="spa6-11">Advanced Simple</entry> - <entry spanname="spa12-17">DivX</entry> - </row> - <row> - <entry>Profile name</entry> - <entry>0</entry> - <entry>1</entry> - <entry>2</entry> - <entry>3</entry> - <entry>0</entry> - <entry>1</entry> - <entry>2</entry> - <entry>3</entry> - <entry>4</entry> - <entry>5</entry> - <entry>Handheld</entry> - <entry>Portable NTSC</entry> - <entry>Portable PAL</entry> - <entry>Home Theater NTSC</entry> - <entry>Home Theater PAL</entry> - <entry>HDTV</entry> - </row> - <row> - <entry>Width [pixels]</entry> - <entry>176</entry> - <entry>176</entry> - <entry>352</entry> - <entry>352</entry> - <entry>176</entry> - <entry>176</entry> - <entry>352</entry> - <entry>352</entry> - <entry>352</entry> - <entry>720</entry> - <entry>176</entry> - <entry>352</entry> - <entry>352</entry> - <entry>720</entry> - <entry>720</entry> - <entry>1280</entry> - </row> - <row> - <entry>Height [pixels]</entry> - <entry>144</entry> - <entry>144</entry> - <entry>288</entry> - <entry>288</entry> - <entry>144</entry> - <entry>144</entry> - <entry>288</entry> - <entry>288</entry> - <entry>576</entry> - <entry>576</entry> - <entry>144</entry> - <entry>240</entry> - <entry>288</entry> - <entry>480</entry> - <entry>576</entry> - <entry>720</entry> - </row> - <row> - <entry>Frame rate [fps]</entry> - <entry>15</entry> - <entry>15</entry> - <entry>15</entry> - <entry>15</entry> - <entry>30</entry> - <entry>30</entry> - <entry>15</entry> - <entry>30</entry> - <entry>30</entry> - <entry>30</entry> - <entry>15</entry> - <entry>30</entry> - <entry>25</entry> - <entry>30</entry> - <entry>25</entry> - <entry>30</entry> - </row> - <row> - <entry>Max average bitrate [kbps]</entry> - <entry>64</entry> - <entry>64</entry> - <entry>128</entry> - <entry>384</entry> - <entry>128</entry> - <entry>128</entry> - <entry>384</entry> - <entry>768</entry> - <entry>3000</entry> - <entry>8000</entry> - <entry>537.6</entry> - <entry>4854</entry> - <entry>4854</entry> - <entry>4854</entry> - <entry>4854</entry> - <entry>9708.4</entry> - </row> - <row> - <entry>Peak average bitrate over 3 secs [kbps]</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>800</entry> - <entry>8000</entry> - <entry>8000</entry> - <entry>8000</entry> - <entry>8000</entry> - <entry>16000</entry> - </row> - <row> - <entry>Max. B-frames</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>0</entry> - <entry>1</entry> - <entry>1</entry> - <entry>1</entry> - <entry>1</entry> - <entry>2</entry> - </row> - <row> - <entry>MPEG quantization</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>Adaptive quantization</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - </row> - <row> - <entry>Interlaced encoding</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - </row> - <row> - <entry>Quaterpixel</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>Global motion compensation</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - </tbody> +<tbody> +<row> + <entry></entry> + <entry spanname="spa2-5">Simple</entry> + <entry spanname="spa6-11">Advanced Simple</entry> + <entry spanname="spa12-17">DivX</entry> +</row> +<row> + <entry>Profile name</entry> + <entry>0</entry> + <entry>1</entry> + <entry>2</entry> + <entry>3</entry> + <entry>0</entry> + <entry>1</entry> + <entry>2</entry> + <entry>3</entry> + <entry>4</entry> + <entry>5</entry> + <entry>Handheld</entry> + <entry>Portable NTSC</entry> + <entry>Portable PAL</entry> + <entry>Home Theater NTSC</entry> + <entry>Home Theater PAL</entry> + <entry>HDTV</entry> +</row> +<row> + <entry>Width [pixels]</entry> + <entry>176</entry> + <entry>176</entry> + <entry>352</entry> + <entry>352</entry> + <entry>176</entry> + <entry>176</entry> + <entry>352</entry> + <entry>352</entry> + <entry>352</entry> + <entry>720</entry> + <entry>176</entry> + <entry>352</entry> + <entry>352</entry> + <entry>720</entry> + <entry>720</entry> + <entry>1280</entry> +</row> +<row> + <entry>Height [pixels]</entry> + <entry>144</entry> + <entry>144</entry> + <entry>288</entry> + <entry>288</entry> + <entry>144</entry> + <entry>144</entry> + <entry>288</entry> + <entry>288</entry> + <entry>576</entry> + <entry>576</entry> + <entry>144</entry> + <entry>240</entry> + <entry>288</entry> + <entry>480</entry> + <entry>576</entry> + <entry>720</entry> +</row> +<row> + <entry>Frame rate [fps]</entry> + <entry>15</entry> + <entry>15</entry> + <entry>15</entry> + <entry>15</entry> + <entry>30</entry> + <entry>30</entry> + <entry>15</entry> + <entry>30</entry> + <entry>30</entry> + <entry>30</entry> + <entry>15</entry> + <entry>30</entry> + <entry>25</entry> + <entry>30</entry> + <entry>25</entry> + <entry>30</entry> +</row> +<row> + <entry>Max average bitrate [kbps]</entry> + <entry>64</entry> + <entry>64</entry> + <entry>128</entry> + <entry>384</entry> + <entry>128</entry> + <entry>128</entry> + <entry>384</entry> + <entry>768</entry> + <entry>3000</entry> + <entry>8000</entry> + <entry>537.6</entry> + <entry>4854</entry> + <entry>4854</entry> + <entry>4854</entry> + <entry>4854</entry> + <entry>9708.4</entry> +</row> +<row> + <entry>Peak average bitrate over 3 secs [kbps]</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>800</entry> + <entry>8000</entry> + <entry>8000</entry> + <entry>8000</entry> + <entry>8000</entry> + <entry>16000</entry> +</row> +<row> + <entry>Max. B-frames</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>0</entry> + <entry>1</entry> + <entry>1</entry> + <entry>1</entry> + <entry>1</entry> + <entry>2</entry> +</row> +<row> + <entry>MPEG quantization</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> +</row> +<row> + <entry>Adaptive quantization</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> +</row> +<row> + <entry>Interlaced encoding</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> +</row> +<row> + <entry>Quaterpixel</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> +</row> +<row> + <entry>Global motion compensation</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> +</row> +</tbody> </tgroup> </informaltable> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-xvid-example-settings"> <title>Encoding setting examples</title> <para> - The following settings are examples of different encoding - option combinations that affect the speed vs quality tradeoff - at the same target bitrate. -</para> - -<para> - All the encoding settings were tested on a 720x448 @30000/1001 fps - video sample, the target bitrate was 900kbps, and the machine was an - AMD-64 3400+ at 2400 MHz in 64 bits mode. - Each encoding setting features the measured encoding speed (in - frames per second) and the PSNR loss (in dB) compared to the "very - high quality" setting. - Please understand that depending on your source, your machine type - and development advancements, you may get very different results. -</para> - -<para> +The following settings are examples of different encoding +option combinations that affect the speed vs quality tradeoff +at the same target bitrate. +</para> + +<para> +All the encoding settings were tested on a 720x448 @30000/1001 fps +video sample, the target bitrate was 900kbps, and the machine was an +AMD-64 3400+ at 2400 MHz in 64 bits mode. +Each encoding setting features the measured encoding speed (in +frames per second) and the PSNR loss (in dB) compared to the "very +high quality" setting. +Please understand that depending on your source, your machine type +and development advancements, you may get very different results. +</para> + <informaltable frame="all"> <tgroup cols="4"> <thead> @@ -3445,91 +3539,104 @@ </tbody> </tgroup> </informaltable> -</para> </sect2> - </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="menc-feat-x264"> -<title>Encoding with the <systemitem class="library">x264</systemitem> codec</title> -<para> - <systemitem class="library">x264</systemitem> is a free library for - encoding H.264/AVC video streams. - Before starting to encode, you need to <link linkend="codec-x264-encode"> - set up <application>MEncoder</application> to support it</link>. -</para> +<title>Encoding with the + <systemitem class="library">x264</systemitem> codec</title> + +<para> +<systemitem class="library">x264</systemitem> is a free library for +encoding H.264/AVC video streams. +Before starting to encode, you need to +<link linkend="codec-x264-encode">set up <application>MEncoder</application> to support it</link>. +</para> + +<!-- ********** --> <sect2 id="menc-feat-x264-encoding-options"> <title>Encoding options of x264</title> <para> - Please begin by reviewing the - <systemitem class="library">x264</systemitem> section of - <application>MPlayer</application>'s man page. - This section is intended to be a supplement to the man page. - Here you will find quick hints about which options are most - likely to interest most people. The man page is more terse, - but also more exhaustive, and it sometimes offers much better - technical detail. -</para> +Please begin by reviewing the +<systemitem class="library">x264</systemitem> section of +<application>MPlayer</application>'s man page. +This section is intended to be a supplement to the man page. +Here you will find quick hints about which options are most +likely to interest most people. The man page is more terse, +but also more exhaustive, and it sometimes offers much better +technical detail. +</para> + <sect3 id="menc-feat-x264-encoding-options-intro"> <title>Introduction</title> -<para>This guide considers two major categories of encoding options:</para> + +<para> +This guide considers two major categories of encoding options: +</para> <orderedlist> - <listitem><para>Options which mainly trade off encoding time vs. quality - </para></listitem> - <listitem><para>Options which may be useful for fulfilling various personal - preferences and special requirements</para></listitem> +<listitem><para> + Options which mainly trade off encoding time vs. quality +</para></listitem> +<listitem><para> + Options which may be useful for fulfilling various personal + preferences and special requirements +</para></listitem> </orderedlist> <para> - Ultimately, only you can decide which options are best for your - purposes. The decision for the first class of options is the simplest: - you only have to decide whether you think the quality differences - justify the speed differences. For the second class of options, - preferences may be far more subjective, and more factors may be - involved. Note that some of the "personal preferences and special - requirements" options can still have large impacts on speed or quality, - but that is not what they are primarily useful for. A couple of the - "personal preference" options may even cause changes that look better - to some people, but look worse to others. -</para> - -<para> - Before continuing, you need to understand that this guide uses only one - quality metric: global PSNR. - For a brief explanation of what PSNR is, see - <ulink url="http://en.wikipedia.org/wiki/PSNR">the Wikipedia article on PSNR</ulink>. - Global PSNR is the last PSNR number reported when you include - the <option>psnr</option> option in <option>x264encopts</option>. - Any time you read a claim about PSNR, one of the assumptions - behind the claim is that equal bitrates are used. -</para> - -<para> - Nearly all of this guide's comments assume you are using - two pass. - When comparing options, there are two major reasons for using - two pass encoding. - First, using two pass often gains around 1dB PSNR, which is a - very big difference. - Secondly, testing options by doing direct quality comparisons - with one pass encodes introduces a major confounding - factor: bitrate often varies significantly with each encode. - It is not always easy to tell whether quality changes are due - mainly to changed options, or if they mostly reflect essentially - random differences in the achieved bitrate. -</para> - +Ultimately, only you can decide which options are best for your +purposes. The decision for the first class of options is the simplest: +you only have to decide whether you think the quality differences +justify the speed differences. For the second class of options, +preferences may be far more subjective, and more factors may be +involved. Note that some of the "personal preferences and special +requirements" options can still have large impacts on speed or quality, +but that is not what they are primarily useful for. A couple of the +"personal preference" options may even cause changes that look better +to some people, but look worse to others. +</para> + +<para> +Before continuing, you need to understand that this guide uses only one +quality metric: global PSNR. +For a brief explanation of what PSNR is, see +<ulink url="http://en.wikipedia.org/wiki/PSNR">the Wikipedia article on PSNR</ulink>. +Global PSNR is the last PSNR number reported when you include +the <option>psnr</option> option in <option>x264encopts</option>. +Any time you read a claim about PSNR, one of the assumptions +behind the claim is that equal bitrates are used. +</para> + +<para> +Nearly all of this guide's comments assume you are using two pass. +When comparing options, there are two major reasons for using +two pass encoding. +First, using two pass often gains around 1dB PSNR, which is a +very big difference. +Secondly, testing options by doing direct quality comparisons +with one pass encodes introduces a major confounding +factor: bitrate often varies significantly with each encode. +It is not always easy to tell whether quality changes are due +mainly to changed options, or if they mostly reflect essentially +random differences in the achieved bitrate. +</para> </sect3> + <sect3 id="menc-feat-x264-encoding-options-speedvquality"> <title>Options which primarily affect speed and quality</title> <itemizedlist> -<listitem><para> +<listitem> + <para> <emphasis role="bold">subq</emphasis>: Of the options which allow you to trade off speed for quality, <option>subq</option> and <option>frameref</option> (see below) are usually @@ -3548,8 +3655,8 @@ Typically, <option>subq=5</option> achieves 0.2-0.5 dB higher global PSNR in comparison <option>subq=1</option>. This is usually enough to be visible. -</para> -<para> + </para> + <para> <option>subq=6</option> is the slowest, highest quality mode. In comparison to <option>subq=5</option>, it usually gains 0.1-0.4 dB global PSNR with speed costs varying from 25%-100%. @@ -3561,18 +3668,17 @@ and quality in complex, high motion scenes, but it may not have much effect in low-motion scenes. Note that it is still recommended to always set <option>bframes</option> to something other than zero (see below). -</para></listitem> -<listitem><para> + </para> +</listitem> +<listitem> + <para> <emphasis role="bold">frameref</emphasis>: <option>frameref</option> is set to 1 by default, but this - should not be taken to imply that it is reasonable to set it - to 1. + should not be taken to imply that it is reasonable to set it to 1. Merely raising <option>frameref</option> to 2 gains around - 0.15dB PSNR with a 5-10% speed penalty; this seems like a - good tradeoff. + 0.15dB PSNR with a 5-10% speed penalty; this seems like a good tradeoff. <option>frameref=3</option> gains around 0.25dB PSNR over - <option>frameref=1</option>, which should be a visible - difference. + <option>frameref=1</option>, which should be a visible difference. <option>frameref=3</option> is around 15% slower than <option>frameref=1</option>. Unfortunately, diminishing returns set in rapidly. @@ -3581,8 +3687,7 @@ 15% speed penalty. Above <option>frameref=6</option>, the quality gains are usually very small (although you should keep in mind throughout - this whole discussion that it can vary quite a lot depending on - your source). + this whole discussion that it can vary quite a lot depending on your source). In a fairly typical case, <option>frameref=12</option> will improve global PSNR by a tiny 0.02dB over <option>frameref=6</option>, at a speed cost of 15%-20%. @@ -3591,9 +3696,9 @@ almost certainly never <emphasis role="bold">harm</emphasis> PSNR, but the additional quality benefits are barely even measurable, let alone perceptible. -</para> -<note><title>Note:</title> -<para> + </para> + <note><title>Note:</title> + <para> Raising <option>frameref</option> to unnecessarily high values <emphasis role="bold">can</emphasis> and <emphasis role="bold">usually does</emphasis> @@ -3602,9 +3707,8 @@ <option>frameref</option> "too high" currently seems too remote to even worry about, and in the future, optimizations may remove the possibility altogether. -</para> -</note> -<para> + </para></note> + <para> If you care about speed, a reasonable compromise is to use low <option>subq</option> and <option>frameref</option> values on the first pass, and then raise them on the second pass. @@ -3624,9 +3728,10 @@ <option>frameref</option> to 3 or higher. This issue is probably extremely rare in live action video material, but it does sometimes come up in video game captures. -</para></listitem> - -<listitem><para> + </para> +</listitem> +<listitem> + <para> <emphasis role="bold">me</emphasis>: This option is for choosing the motion estimation search method. Altering this option provides a straightforward quality-vs-speed @@ -3640,13 +3745,12 @@ is about 40% slower than the default <option> me=hex</option>. With <option>frameref=3</option>, the speed penalty incurred drops to 25%-30%. -</para> -<para> + </para> + <para> <option>me=esa</option> uses an exhaustive search that is too slow for practical use. -</para> + </para> </listitem> - <listitem><para> <emphasis role="bold">partitions=all</emphasis>: This option enables the use of 8x4, 4x8 and 4x4 subpartitions in @@ -3656,10 +3760,9 @@ containing only low motion, however in some high-motion source, particularly source with lots of small moving objects, gains of about 0.1dB can be expected. -</para> -</listitem> - -<listitem><para> +</para></listitem> +<listitem> + <para> <emphasis role="bold">bframes</emphasis>: If you are used to encoding with other codecs, you may have found that B-frames are not always useful. @@ -3670,8 +3773,8 @@ It is interesting to note that using B-frames usually speeds up the second pass somewhat, and may also speed up a single pass encode if adaptive B-frame decision is turned off. -</para> -<para> + </para> + <para> With adaptive B-frame decision turned off (<option>x264encopts</option>'s <option>nob_adapt</option>), the optimal value for this setting is usually no more than @@ -3681,13 +3784,14 @@ B-frames in scenes where they would hurt compression. The encoder rarely chooses to use more than 3 or 4 B-frames; setting this option any higher will have little effect. -</para></listitem> - -<listitem><para> + </para> +</listitem> +<listitem> + <para> <emphasis role="bold">b_adapt</emphasis>: Note: This is on by default. -</para> -<para> + </para> + <para> With this option enabled, the encoder will use a reasonably fast decision process to reduce the number of B-frames used in scenes that might not benefit from them as much. @@ -3700,8 +3804,8 @@ first pass. <option>b_adapt</option> and <option>b_bias</option> have no effect on subsequent passes. -</para></listitem> - + </para> +</listitem> <listitem><para> <emphasis role="bold">b_pyramid</emphasis>: You might as well enable this option if you are using >=2 B-frames; @@ -3710,8 +3814,8 @@ Note that these videos cannot be read by libavcodec-based decoders older than about March 5, 2005. </para></listitem> - -<listitem><para> +<listitem> + <para> <emphasis role="bold">weight_b</emphasis>: In typical cases, there is not much gain with this option. However, in crossfades or fade-to-black scenes, weighted @@ -3724,22 +3828,26 @@ Also, contrary to what some people seem to guess, the decoder CPU requirements are not much affected by weighted prediction, all else being equal. -</para> -<para> + </para> + <para> Unfortunately, the current adaptive B-frame decision algorithm has a strong tendency to avoid B-frames during fades. Until this changes, it may be a good idea to add <option>nob_adapt</option> to your x264encopts, if you expect fades to have a large effect in your particular video clip. -</para></listitem> + </para> +</listitem> </itemizedlist> </sect3> + <sect3 id="menc-feat-x264-encoding-options-misc-preferences"> <title>Options pertaining to miscellaneous preferences</title> + <itemizedlist> -<listitem><para> +<listitem> + <para> <emphasis role="bold">Two pass encoding</emphasis>: Above, it was suggested to always use two pass encoding, but there are still reasons for not using it. For instance, if you are capturing @@ -3747,8 +3855,8 @@ Also, one pass is obviously faster than two passes; if you use the exact same set of options on both passes, two pass encoding is almost twice as slow. -</para> -<para> + </para> + <para> Still, there are very good reasons for using two pass encoding. For one thing, single pass ratecontrol is not psychic, and it often makes unreasonable choices because it cannot see the big picture. For example, @@ -3772,8 +3880,8 @@ it would have taken to make it look decent. There are ways to mitigate the pitfalls of single-pass encoding, but they may tend to increase bitrate misprediction. -</para> -<para> + </para> + <para> Multipass ratecontrol can offer huge advantages over a single pass. Using the statistics gathered from the first pass encode, the encoder can estimate, with reasonable accuracy, the "cost" (in bits) of @@ -3782,8 +3890,8 @@ expensive (high-motion) and cheap (low-motion) scenes. See <option>qcomp</option> below for some ideas on how to tweak this allocation to your liking. -</para> -<para> + </para> + <para> Moreover, two passes need not take twice as long as one pass. You can tweak the options in the first pass for higher speed and lower quality. If you choose your options well, you can get a very fast first pass. @@ -3794,10 +3902,10 @@ <option>x264encopts</option>. Then, on the second pass, use slower, higher-quality options: <option>subq=6:frameref=15:partitions=all:me=umh</option> -</para></listitem> + </para> +</listitem> <listitem><para> <emphasis role="bold">Three pass encoding</emphasis>? - x264 offers the ability to make an arbitrary number of consecutive passes. If you specify <option>pass=1</option> on the first pass, then use <option>pass=3</option> on a subsequent pass, the subsequent @@ -3813,7 +3921,6 @@ also a few special cases in which three (or more) passes are handy for advanced users, but for brevity, this guide omits discussing those special cases. - </para></listitem> <listitem><para> <emphasis role="bold">qcomp</emphasis>: @@ -3845,11 +3952,12 @@ vanishingly low, or even zero). The video stream will still have seekable points as long as there are some scene changes. </para></listitem> -<listitem><para> +<listitem> + <para> <emphasis role="bold">deblock</emphasis>: This topic is going to be a bit controversial. -</para> -<para> + </para> + <para> H.264 defines a simple deblocking procedure on I-blocks that uses pre-set strengths and thresholds depending on the QP of the block in question. @@ -3858,17 +3966,17 @@ The pre-set strengths defined by the standard are well-chosen and the odds are very good that they are PSNR-optimal for whatever video you are trying to encode. - The <option>deblock</option> allow you to specify offsets to the preset deblocking - thresholds. -</para> -<para> + The <option>deblock</option> allow you to specify offsets to the preset + deblocking thresholds. + </para> + <para> Many people seem to think it is a good idea to lower the deblocking filter strength by large amounts (say, -3). This is however almost never a good idea, and in most cases, people who are doing this do not understand very well how deblocking works by default. -</para> -<para> + </para> + <para> The first and most important thing to know about the in-loop deblocking filter is that the default thresholds are almost always PSNR-optimal. @@ -3878,8 +3986,8 @@ guaranteed to hurt PSNR. Strengthening the filter will smear more details; weakening the filter will increase the appearance of blockiness. -</para> -<para> + </para> + <para> It is definitely a bad idea to lower the deblocking thresholds if your source is mainly low in spacial complexity (i.e., not a lot of detail or noise). @@ -3896,9 +4004,8 @@ By lowering the deblocking filter strength, you are most likely increasing error by adding ringing artifacts, but the eye does not notice because it confuses the artifacts with detail. -</para> - -<para> + </para> + <para> This <emphasis role="bold">still</emphasis> does not justify lowering the deblocking filter strength, however. You can generally get better quality noise from postprocessing. @@ -3908,36 +4015,43 @@ artifacting. It will almost certainly look better than the results you would have gotten just by fiddling with the deblocking filter. -</para></listitem> + </para> +</listitem> </itemizedlist> </sect3> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-x264-example-settings"> <title>Encoding setting examples</title> <para> - The following settings are examples of different encoding - option combinations that affect the speed vs quality tradeoff - at the same target bitrate. -</para> - -<para> - All the encoding settings were tested on a 720x448 @30000/1001 fps - video sample, the target bitrate was 900kbps, and the machine was an - AMD-64 3400+ at 2400 MHz in 64 bits mode. - Each encoding setting features the measured encoding speed (in - frames per second) and the PSNR loss (in dB) compared to the "very - high quality" setting. - Please understand that depending on your source, your machine type - and development advancements, you may get very different results. -</para> - -<para> +The following settings are examples of different encoding +option combinations that affect the speed vs quality tradeoff +at the same target bitrate. +</para> + +<para> +All the encoding settings were tested on a 720x448 @30000/1001 fps +video sample, the target bitrate was 900kbps, and the machine was an +AMD-64 3400+ at 2400 MHz in 64 bits mode. +Each encoding setting features the measured encoding speed (in +frames per second) and the PSNR loss (in dB) compared to the "very +high quality" setting. +Please understand that depending on your source, your machine type +and development advancements, you may get very different results. +</para> + <informaltable frame="all"> <tgroup cols="4"> <thead> -<row><entry>Description</entry><entry>Encoding options</entry><entry>speed (in fps)</entry><entry>Relative PSNR loss (in dB)</entry></row> +<row> + <entry>Description</entry> + <entry>Encoding options</entry> + <entry>speed (in fps)</entry> + <entry>Relative PSNR loss (in dB)</entry> +</row> </thead> <tbody> <row> @@ -3961,18 +4075,24 @@ </tbody> </tgroup> </informaltable> -</para> </sect2> - </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="menc-feat-video-for-windows"> -<title>Encoding with the <systemitem class="library">Video For Windows</systemitem> codec family</title> +<title> + Encoding with the <systemitem class="library">Video For Windows</systemitem> + codec family +</title> <para> Video for Windows provides simple encoding by means of binary video codecs. You can encode with the following codecs (if you have more, please tell us!) </para> + <para> Note that support for this is very experimental and some codecs may not work correctly. Some codecs will only work in certain colorspaces, try @@ -3980,6 +4100,8 @@ if a codec fails or gives wrong output. </para> +<!-- ********** --> + <sect2 id="menc-feat-enc-vfw-video-codecs"> <title>Video for Windows supported codecs</title> @@ -3988,10 +4110,10 @@ <tgroup cols="4"> <thead> <row> -<entry>Video codec file name</entry> -<entry>Description (FourCC)</entry> -<entry>md5sum</entry> -<entry>Comment</entry> + <entry>Video codec file name</entry> + <entry>Description (FourCC)</entry> + <entry>md5sum</entry> + <entry>Comment</entry> </row> </thead> <tbody> @@ -4102,8 +4224,8 @@ <entry>MSU Lossless codec (MSUD)</entry> <entry>294bf9288f2f127bb86f00bfcc9ccdda</entry> <entry> - Decodable by <application>Window Media Player</application>, - not <application>MPlayer</application> (yet). + Decodable by <application>Window Media Player</application>, + not <application>MPlayer</application> (yet). </entry> </row> <row> @@ -4117,43 +4239,53 @@ </informaltable> The first column contains the codec names that should be passed after the -<literal>codec</literal> parameter, like: <option>-xvfwopts codec=divx.dll</option> +<literal>codec</literal> parameter, +like: <option>-xvfwopts codec=divx.dll</option> The FourCC code used by each codec is given in the parentheses. </para> + <informalexample> <para> An example with VP3 compression: -<screen>mencoder dvd://2 -o title2.avi -ovc vfw -xvfwopts codec=vp31vfw.dll -oac copy</screen> +<screen> +mencoder dvd://2 -o <replaceable>title2.avi</replaceable> -ovc vfw -xvfwopts codec=vp31vfw.dll -oac copy +</screen> </para> </informalexample> </sect2> </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="menc-feat-vcd-dvd"> -<title>Using <application>MEncoder</application> to create VCD/SVCD/DVD-compliant files.</title> +<title>Using <application>MEncoder</application> + to create VCD/SVCD/DVD-compliant files</title> <sect2 id="menc-feat-vcd-dvd-constraints"> <title>Format Constraints</title> -<para> - <application>MEncoder</application> is capable of creating VCD, SCVD - and DVD format MPEG files using the - <systemitem class="library">libavcodec</systemitem> library. - These files can then be used in conjunction with - <ulink url="http://www.gnu.org/software/vcdimager/vcdimager.html">vcdimager</ulink> - or - <ulink url="http://dvdauthor.sourceforge.net/">dvdauthor</ulink> - to create discs that will play on a standard set-top player. -</para> - -<para> - The DVD, SVCD, and VCD formats are subject to heavy constraints. - Only a small selection of encoded picture sizes and aspect ratios are - available. - If your movie does not already meet these requirements, you may have - to scale,crop or add black borders to the picture to make it - compliant. -</para> + +<para> +<application>MEncoder</application> is capable of creating VCD, SCVD +and DVD format MPEG files using the +<systemitem class="library">libavcodec</systemitem> library. +These files can then be used in conjunction with +<ulink url="http://www.gnu.org/software/vcdimager/vcdimager.html">vcdimager</ulink> +or +<ulink url="http://dvdauthor.sourceforge.net/">dvdauthor</ulink> +to create discs that will play on a standard set-top player. +</para> + +<para> +The DVD, SVCD, and VCD formats are subject to heavy constraints. +Only a small selection of encoded picture sizes and aspect ratios are +available. +If your movie does not already meet these requirements, you may have +to scale,crop or add black borders to the picture to make it +compliant. +</para> + <sect3 id="menc-feat-vcd-dvd-constraints-resolution"> <title>Format Constraints</title> @@ -4161,299 +4293,296 @@ <informaltable frame="all"> <tgroup cols="9"> <thead> - <row> - <entry>Format</entry> - <entry>Resolution</entry> - <entry>V. Codec</entry> - <entry>V. Bitrate</entry> - <entry>Sample Rate</entry> - <entry>A. Codec</entry> - <entry>A. Bitrate</entry> - <entry>FPS</entry> - <entry>Aspect</entry> - </row> +<row> + <entry>Format</entry> + <entry>Resolution</entry> + <entry>V. Codec</entry> + <entry>V. Bitrate</entry> + <entry>Sample Rate</entry> + <entry>A. Codec</entry> + <entry>A. Bitrate</entry> + <entry>FPS</entry> + <entry>Aspect</entry> +</row> </thead> <tbody> - <row> - <entry>NTSC DVD</entry> - <entry>720x480, 704x480, 352x480, 352x240</entry> - <entry>MPEG-2</entry> - <entry>9800 kbps</entry> - <entry>48000 Hz</entry> - <entry>AC3,PCM</entry> - <entry>1536 kbps (max)</entry> - <entry>30000/1001, 24000/1001</entry> - <entry>4:3, 16:9 (only for 720x480)</entry> - </row> - <row> - <entry>NTSC DVD</entry> - <entry>352x240<footnote id='fn-rare-resolutions'><para> - These resolutions are rarely used for DVDs because - they are fairly low quality.</para></footnote></entry> - <entry>MPEG-1</entry> - <entry>1856 kbps</entry> - <entry>48000 Hz</entry> - <entry>AC3,PCM</entry> - <entry>1536 kbps (max)</entry> - <entry>30000/1001, 24000/1001</entry> - <entry>4:3, 16:9</entry> - </row> - <row> - <entry>NTSC SVCD</entry> - <entry>480x480</entry> - <entry>MPEG-2</entry> - <entry>2600 kbps</entry> - <entry>44100 Hz</entry> - <entry>MP2</entry> - <entry>384 kbps (max)</entry> - <entry>30000/1001</entry> - <entry>4:3</entry> - </row> - <row> - <entry>NTSC VCD</entry> - <entry>352x240</entry> - <entry>MPEG-1</entry> - <entry>1150 kbps</entry> - <entry>44100 Hz</entry> - <entry>MP2</entry> - <entry>224 kbps</entry> - <entry>24000/1001, 30000/1001</entry> - <entry>4:3</entry> - </row> - <row> - <entry>PAL DVD</entry> - <entry>720x576, 704x576, 352x576, 352x288</entry> - <entry>MPEG-2</entry> - <entry>9800 kbps</entry> - <entry>48000 Hz</entry> - <entry>MP2,AC3,PCM</entry> - <entry>1536 kbps (max)</entry> - <entry>25</entry> - <entry>4:3, 16:9 (only for 720x576)</entry> - </row> - <row> - <entry>PAL DVD</entry> - <entry>352x288<footnoteref linkend='fn-rare-resolutions'/></entry> - <entry>MPEG-1</entry> - <entry>1856 kbps</entry> - <entry>48000 Hz</entry> - <entry>MP2,AC3,PCM</entry> - <entry>1536 kbps (max)</entry> - <entry>25</entry> - <entry>4:3, 16:9</entry> - </row> - <row> - <entry>PAL SVCD</entry> - <entry>480x576</entry> - <entry>MPEG-2</entry> - <entry>2600 kbps</entry> - <entry>44100 Hz</entry> - <entry>MP2</entry> - <entry>384 kbps (max)</entry> - <entry>25</entry> - <entry>4:3</entry> - </row> - <row> - <entry>PAL VCD</entry> - <entry>352x288</entry> - <entry>MPEG-1</entry> - <entry>1152 kbps</entry> - <entry>44100 Hz</entry> - <entry>MP2</entry> - <entry>224 kbps</entry> - <entry>25</entry> - <entry>4:3</entry> - </row> +<row> + <entry>NTSC DVD</entry> + <entry>720x480, 704x480, 352x480, 352x240</entry> + <entry>MPEG-2</entry> + <entry>9800 kbps</entry> + <entry>48000 Hz</entry> + <entry>AC3,PCM</entry> + <entry>1536 kbps (max)</entry> + <entry>30000/1001, 24000/1001</entry> + <entry>4:3, 16:9 (only for 720x480)</entry> +</row> +<row> + <entry>NTSC DVD</entry> + <entry>352x240<footnote id='fn-rare-resolutions'><para> + These resolutions are rarely used for DVDs because + they are fairly low quality.</para></footnote></entry> + <entry>MPEG-1</entry> + <entry>1856 kbps</entry> + <entry>48000 Hz</entry> + <entry>AC3,PCM</entry> + <entry>1536 kbps (max)</entry> + <entry>30000/1001, 24000/1001</entry> + <entry>4:3, 16:9</entry> +</row> +<row> + <entry>NTSC SVCD</entry> + <entry>480x480</entry> + <entry>MPEG-2</entry> + <entry>2600 kbps</entry> + <entry>44100 Hz</entry> + <entry>MP2</entry> + <entry>384 kbps (max)</entry> + <entry>30000/1001</entry> + <entry>4:3</entry> +</row> +<row> + <entry>NTSC VCD</entry> + <entry>352x240</entry> + <entry>MPEG-1</entry> + <entry>1150 kbps</entry> + <entry>44100 Hz</entry> + <entry>MP2</entry> + <entry>224 kbps</entry> + <entry>24000/1001, 30000/1001</entry> + <entry>4:3</entry> +</row> +<row> + <entry>PAL DVD</entry> + <entry>720x576, 704x576, 352x576, 352x288</entry> + <entry>MPEG-2</entry> + <entry>9800 kbps</entry> + <entry>48000 Hz</entry> + <entry>MP2,AC3,PCM</entry> + <entry>1536 kbps (max)</entry> + <entry>25</entry> + <entry>4:3, 16:9 (only for 720x576)</entry> +</row> +<row> + <entry>PAL DVD</entry> + <entry>352x288<footnoteref linkend='fn-rare-resolutions'/></entry> + <entry>MPEG-1</entry> + <entry>1856 kbps</entry> + <entry>48000 Hz</entry> + <entry>MP2,AC3,PCM</entry> + <entry>1536 kbps (max)</entry> + <entry>25</entry> + <entry>4:3, 16:9</entry> +</row> +<row> + <entry>PAL SVCD</entry> + <entry>480x576</entry> + <entry>MPEG-2</entry> + <entry>2600 kbps</entry> + <entry>44100 Hz</entry> + <entry>MP2</entry> + <entry>384 kbps (max)</entry> + <entry>25</entry> + <entry>4:3</entry> +</row> +<row> + <entry>PAL VCD</entry> + <entry>352x288</entry> + <entry>MPEG-1</entry> + <entry>1152 kbps</entry> + <entry>44100 Hz</entry> + <entry>MP2</entry> + <entry>224 kbps</entry> + <entry>25</entry> + <entry>4:3</entry> +</row> </tbody> </tgroup> </informaltable> <para> - If your movie has 2.35:1 aspect (most recent action movies), you will - have to add black borders or crop the movie down to 16:9 to make a DVD - or VCD. - If you add black borders, try to align them at 16-pixel boundaries in - order to minimize the impact on encoding performance. - Thankfully DVD has sufficiently excessive bitrate that you do not have - to worry too much about encoding efficiency, but SVCD and VCD are - highly bitrate-starved and require effort to obtain acceptable quality. +If your movie has 2.35:1 aspect (most recent action movies), you will +have to add black borders or crop the movie down to 16:9 to make a DVD or VCD. +If you add black borders, try to align them at 16-pixel boundaries in +order to minimize the impact on encoding performance. +Thankfully DVD has sufficiently excessive bitrate that you do not have +to worry too much about encoding efficiency, but SVCD and VCD are +highly bitrate-starved and require effort to obtain acceptable quality. </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-constraints-gop"> <title>GOP Size Constraints</title> -<para> - DVD, VCD, and SVCD also constrain you to relatively low - GOP (Group of Pictures) sizes. - For 30 fps material the largest allowed GOP size is 18. - For 25 or 24 fps, the maximum is 15. - The GOP size is set using the <option>keyint</option> option. + +<para> +DVD, VCD, and SVCD also constrain you to relatively low +GOP (Group of Pictures) sizes. +For 30 fps material the largest allowed GOP size is 18. +For 25 or 24 fps, the maximum is 15. +The GOP size is set using the <option>keyint</option> option. </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-constraints-bitrate"> <title>Bitrate Constraints</title> -<para> - VCD video is required to be CBR at 1152 kbps. - This highly limiting constraint also comes along with an extremly low vbv - buffer size of 327 kilobits. - SVCD allows varying video bitrates up to 2500 kbps, and a somewhat less - restrictive vbv buffer size of 917 kilobits is allowed. - DVD video bitrates may range anywhere up to 9800 kbps (though typical - bitrates are about half that), and the vbv buffer size is 1835 kilobits. + +<para> +VCD video is required to be CBR at 1152 kbps. +This highly limiting constraint also comes along with an extremly low vbv +buffer size of 327 kilobits. +SVCD allows varying video bitrates up to 2500 kbps, and a somewhat less +restrictive vbv buffer size of 917 kilobits is allowed. +DVD video bitrates may range anywhere up to 9800 kbps (though typical +bitrates are about half that), and the vbv buffer size is 1835 kilobits. </para> </sect3> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-vcd-dvd-output"> <title>Output Options</title> -<para> - <application>MEncoder</application> has options to control the output - format. - Using these options we can instruct it to create the correct type of - file. -</para> - -<para> - The options for VCD and SVCD are called xvcd and xsvcd, because they - are extended formats. - They are not strictly compliant, mainly because the output does not - contain scan offsets. - If you need to generate an SVCD image, you should pass the output file - to - <ulink url="http://www.gnu.org/software/vcdimager/vcdimager.html">vcdimager</ulink>. -</para> - -<para> - VCD: - <screen> - -of mpeg -mpegopts format=xvcd - </screen> -</para> - -<para> - SVCD: - <screen> - -of mpeg -mpegopts format=xsvcd - </screen> -</para> - -<para> - DVD (with timestamps on every frame, if possible): - <screen> - -of mpeg -mpegopts format=dvd:tsaf - </screen> -</para> - -<para> - DVD with NTSC Pullup: - <screen> - -of mpeg -mpegopts format=dvd:tsaf:telecine -ofps 24000/1001 - </screen> - This allows 24000/1001 fps progressive content to be encoded at 30000/1001 - fps whilst maintaing DVD-compliance. -</para> + +<para> +<application>MEncoder</application> has options to control the output +format. +Using these options we can instruct it to create the correct type of +file. +</para> + +<para> +The options for VCD and SVCD are called xvcd and xsvcd, because they +are extended formats. +They are not strictly compliant, mainly because the output does not +contain scan offsets. +If you need to generate an SVCD image, you should pass the output file to +<ulink url="http://www.gnu.org/software/vcdimager/vcdimager.html">vcdimager</ulink>. +</para> + +<para> +VCD: +<screen>-of mpeg -mpegopts format=xvcd</screen> +</para> + +<para> +SVCD: +<screen>-of mpeg -mpegopts format=xsvcd</screen> +</para> + +<para> +DVD (with timestamps on every frame, if possible): +<screen>-of mpeg -mpegopts format=dvd:tsaf</screen> +</para> + +<para> +DVD with NTSC Pullup: +<screen>-of mpeg -mpegopts format=dvd:tsaf:telecine -ofps 24000/1001</screen> +This allows 24000/1001 fps progressive content to be encoded at 30000/1001 +fps whilst maintaing DVD-compliance. +</para> + <sect3 id="menc-feat-vcd-dvd-output-aspect"> <title>Aspect Ratio</title> -<para> - The aspect argument of <option>-lavcopts</option> is used to encode - the aspect ratio of the file. - During playback the aspect ratio is used to restore the video to the - correct size. -</para> - -<para> - 16:9 or "Widescreen" - <screen> - -lavcopts aspect=16/9 - </screen> -</para> - -<para> - 4:3 or "Fullscreen" - <screen> - -lavcopts aspect=4/3 - </screen> -</para> - -<para> - 2.35:1 or "Cinemascope" NTSC - <screen> - -vf scale=720:368,expand=720:480 -lavcopts aspect=16/9 - </screen> - To calculate the correct scaling size, use the expanded NTSC width of - 854/2.35 = 368 -</para> - -<para> - 2.35:1 or "Cinemascope" PAL - <screen> - -vf scale="720:432,expand=720:576 -lavcopts aspect=16/9 - </screen> - To calculate the correct scaling size, use the expanded PAL width of - 1024/2.35 = 432 -</para> - + +<para> +The aspect argument of <option>-lavcopts</option> is used to encode +the aspect ratio of the file. +During playback the aspect ratio is used to restore the video to the +correct size. +</para> + +<para> +16:9 or "Widescreen" +<screen>-lavcopts aspect=16/9</screen> +</para> + +<para> +4:3 or "Fullscreen" +<screen>-lavcopts aspect=4/3</screen> +</para> + +<para> +2.35:1 or "Cinemascope" NTSC +<screen>-vf scale=720:368,expand=720:480 -lavcopts aspect=16/9</screen> +To calculate the correct scaling size, use the expanded NTSC width of +854/2.35 = 368 +</para> + +<para> +2.35:1 or "Cinemascope" PAL +<screen>-vf scale="720:432,expand=720:576 -lavcopts aspect=16/9</screen> +To calculate the correct scaling size, use the expanded PAL width of +1024/2.35 = 432 +</para> </sect3> + <sect3 id="menc-feat-vcd-dvd-a-v-sync"> <title>Maintaining A/V sync</title> -<para> - In order to maintain audio/video synchronization throughout the encode, - <application>MEncoder</application> has to drop or duplicate frames. - This works rather well when muxing into an AVI file, but is almost - guaranteed to fail to maintain A/V sync with other muxers such as MPEG. - This is why it is necessary to append the - <option>harddup</option> video filter at the end of the filter chain - to avoid this kind of problem. - You can find more technical information about <option>harddup</option> - in the section - <link linkend="menc-feat-dvd-mpeg4-muxing-filter-issues">Improving muxing and A/V sync reliability</link> - or in the manual page. + +<para> +In order to maintain audio/video synchronization throughout the encode, +<application>MEncoder</application> has to drop or duplicate frames. +This works rather well when muxing into an AVI file, but is almost +guaranteed to fail to maintain A/V sync with other muxers such as MPEG. +This is why it is necessary to append the +<option>harddup</option> video filter at the end of the filter chain +to avoid this kind of problem. +You can find more technical information about <option>harddup</option> +in the section +<link linkend="menc-feat-dvd-mpeg4-muxing-filter-issues">Improving muxing and A/V sync reliability</link> +or in the manual page. </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-output-srate"> <title>Sample Rate Conversion</title> -<para> - If the audio sample rate in the original file is not the same as - required by the target format, sample rate conversion is required. - This is achieved using the <option>-srate</option> option and - the <option>-af lavcresample</option> audio filter together. - </para> - <para> - DVD: - <screen> - -srate 48000 -af lavcresample=48000 - </screen> -</para> -<para> - VCD and SVCD: - <screen> - -srate 44100 -af lavcresample=44100 - </screen> - </para> + +<para> +If the audio sample rate in the original file is not the same as +required by the target format, sample rate conversion is required. +This is achieved using the <option>-srate</option> option and +the <option>-af lavcresample</option> audio filter together. +</para> + +<para> +DVD: +<screen>-srate 48000 -af lavcresample=48000</screen> +</para> + +<para> +VCD and SVCD: +<screen>-srate 44100 -af lavcresample=44100</screen> +</para> </sect3> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-vcd-dvd-lavc"> <title>Using libavcodec for VCD/SVCD/DVD Encoding</title> <sect3 id="menc-feat-vcd-dvd-lavc-intro"> <title>Introduction</title> -<para> - <systemitem class="library">libavcodec</systemitem> can be used to - create VCD/SVCD/DVD compliant video by using the appropriate options. + +<para> +<systemitem class="library">libavcodec</systemitem> can be used to +create VCD/SVCD/DVD compliant video by using the appropriate options. </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-lavc-options"> <title>lavcopts</title> -<para> - This is a list of fields in <option>-lavcopts</option> that you may - be required to change in order to make a complaint movie for VCD, SVCD, - or DVD: + +<para> +This is a list of fields in <option>-lavcopts</option> that you may +be required to change in order to make a complaint movie for VCD, SVCD, +or DVD: </para> <itemizedlist> @@ -4466,14 +4595,12 @@ Note that MP3 audio is not compliant for any of these formats, but players often have no problem playing it anyway. </para></listitem> - <listitem><para> <emphasis role="bold">abitrate</emphasis>: 224 for VCD; up to 384 for SVCD; up to 1536 for DVD, but commonly used values range from 192 kbps for stereo to 384 kbps for 5.1 channel sound. </para></listitem> - <listitem><para> <emphasis role="bold">vcodec</emphasis>: <option>mpeg1video</option> for VCD; @@ -4481,7 +4608,6 @@ <option>mpeg2video</option> is usually used for DVD but you may also use <option>mpeg1video</option> for CIF resolutions. </para></listitem> - <listitem><para> <emphasis role="bold">keyint</emphasis>: Used to set the GOP size. @@ -4491,24 +4617,20 @@ with most players. A <option>keyint</option> of 25 should never cause any problems. </para></listitem> - <listitem><para> <emphasis role="bold">vrc_buf_size</emphasis>: 327 for VCD, 917 for SVCD, and 1835 for DVD. </para></listitem> - <listitem><para> <emphasis role="bold">vrc_minrate</emphasis>: 1152, for VCD. May be left alone for SVCD and DVD. </para></listitem> - <listitem><para> <emphasis role="bold">vrc_maxrate</emphasis>: 1152 for VCD; 2500 for SVCD; 9800 for DVD. For SVCD and DVD, you might wish to use lower values depending on your own personal preferences and requirements. </para></listitem> - <listitem><para> <emphasis role="bold">vbitrate</emphasis>: 1152 for VCD; @@ -4526,241 +4648,259 @@ </itemizedlist> </sect3> + <sect3 id="menc-feat-vcd-dvd-lavc-examples"> <title>Examples</title> -<para> - This is a typical minimum set of <option>-lavcopts</option> for - encoding video: -</para> -<para> - VCD: - <screen> - -lavcopts vcodec=mpeg1video:vrc_buf_size=327:vrc_minrate=1152:\ - vrc_maxrate=1152:vbitrate=1152:keyint=15:acodec=mp2 - </screen> -</para> - -<para> - SVCD: - <screen> - -lavcopts vcodec=mpeg2video:vrc_buf_size=917:vrc_maxrate=2500:vbitrate=1800:\ - keyint=15:acodec=mp2 - </screen> -</para> - -<para> - DVD: - <screen> - -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:\ - keyint=15:acodec=ac3 - </screen> -</para> - + +<para> +This is a typical minimum set of <option>-lavcopts</option> for +encoding video: +</para> +<para> +VCD: +<screen> +-lavcopts vcodec=mpeg1video:vrc_buf_size=327:vrc_minrate=1152:\ +vrc_maxrate=1152:vbitrate=1152:keyint=15:acodec=mp2 +</screen> +</para> + +<para> +SVCD: +<screen> +-lavcopts vcodec=mpeg2video:vrc_buf_size=917:vrc_maxrate=2500:vbitrate=1800:\ +keyint=15:acodec=mp2 +</screen> +</para> + +<para> +DVD: +<screen> +-lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:\ +keyint=15:acodec=ac3 +</screen> +</para> </sect3> + <sect3 id="menc-feat-vcd-dvd-lavc-advanced"> <title>Advanced Options</title> -<para> - For higher quality encoding, you may also wish to add quality-enhancing - options to lavcopts, such as <option>trell</option>, - <option>mbd=2</option>, and others. - Note that <option>qpel</option> and <option>v4mv</option>, while often - useful with MPEG-4, are not usable with MPEG-1 or MPEG-2. - Also, if you are trying to make a very high quality DVD encode, it may - be useful to add <option>dc=10</option> to lavcopts. - Doing so may help reduce the appearance of blocks in flat-colored areas. - Putting it all together, this is an example of a set of lavcopts for a - higher quality DVD: -</para> - -<para> - <screen> - -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=8000:\ - keyint=15:trell:mbd=2:precmp=2:subcmp=2:cmp=2:dia=-10:predia=-10:cbp:mv0:\ - vqmin=1:lmin=1:dc=10 - </screen> -</para> - + +<para> +For higher quality encoding, you may also wish to add quality-enhancing +options to lavcopts, such as <option>trell</option>, +<option>mbd=2</option>, and others. +Note that <option>qpel</option> and <option>v4mv</option>, while often +useful with MPEG-4, are not usable with MPEG-1 or MPEG-2. +Also, if you are trying to make a very high quality DVD encode, it may +be useful to add <option>dc=10</option> to lavcopts. +Doing so may help reduce the appearance of blocks in flat-colored areas. +Putting it all together, this is an example of a set of lavcopts for a +higher quality DVD: +</para> + +<para> +<screen> +-lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=8000:\ +keyint=15:trell:mbd=2:precmp=2:subcmp=2:cmp=2:dia=-10:predia=-10:cbp:mv0:\ +vqmin=1:lmin=1:dc=10 +</screen> +</para> </sect3> </sect2> +<!-- ********** --> + <sect2 id="menc-feat-vcd-dvd-audio"> <title>Encoding Audio</title> -<para> - VCD and SVCD support MPEG-1 layer II audio, using one of - <systemitem class="library">toolame</systemitem>, - <systemitem class="library">twolame</systemitem>, - or <systemitem class="library">libavcodec</systemitem>'s MP2 encoder. - The libavcodec MP2 is far from being as good as the other two libraries, - however it should always be available to use. - VCD only supports constant bitrate audio (CBR) whereas SVCD supports - variable bitrate (VBR), too. - Be careful when using VBR because some bad standalone players might not - support it too well. -</para> - -<para> - For DVD audio, <systemitem class="library">libavcodec</systemitem>'s - AC3 codec is used. -</para> + +<para> +VCD and SVCD support MPEG-1 layer II audio, using one of +<systemitem class="library">toolame</systemitem>, +<systemitem class="library">twolame</systemitem>, +or <systemitem class="library">libavcodec</systemitem>'s MP2 encoder. +The libavcodec MP2 is far from being as good as the other two libraries, +however it should always be available to use. +VCD only supports constant bitrate audio (CBR) whereas SVCD supports +variable bitrate (VBR), too. +Be careful when using VBR because some bad standalone players might not +support it too well. +</para> + +<para> +For DVD audio, <systemitem class="library">libavcodec</systemitem>'s +AC3 codec is used. +</para> + <sect3 id="menc-feat-vcd-dvd-audio-toolame"> <title>toolame</title> -<para> - For VCD and SVCD: - <screen> - -oac toolame -toolameopts br=224 - </screen> + +<para> +For VCD and SVCD: +<screen>-oac toolame -toolameopts br=224</screen> </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-audio-twolame"> <title>twolame</title> -<para> - For VCD and SVCD: - <screen> - -oac twolame -twolameopts br=224 - </screen> + +<para> +For VCD and SVCD: +<screen>-oac twolame -twolameopts br=224</screen> </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-audio-lavc"> <title>libavcodec</title> -<para> - For DVD with 2 channel sound: - <screen> - -oac lavc -lavcopts acodec=ac3:abitrate=192 - </screen> -</para> -<para> - For DVD with 5.1 channel sound: - <screen> - -channels 6 -oac lavc -lavcopts acodec=ac3:abitrate=384 - </screen> -</para> -<para> - For VCD and SVCD: - <screen> - -oac lavc -lavcopts acodec=mp2:abitrate=224 + +<para> +For DVD with 2 channel sound: +<screen>-oac lavc -lavcopts acodec=ac3:abitrate=192</screen> +</para> + +<para> +For DVD with 5.1 channel sound: +<screen>-channels 6 -oac lavc -lavcopts acodec=ac3:abitrate=384</screen> +</para> + +<para> +For VCD and SVCD: +<screen>-oac lavc -lavcopts acodec=mp2:abitrate=224</screen> +</para> +</sect3> +</sect2> + +<!-- ********** --> + +<sect2 id="menc-feat-vcd-dvd-all"> +<title>Putting it all Together</title> + +<para> +This section shows some complete commands for creating VCD/SVCD/DVD +compliant videos. +</para> + + +<sect3 id="menc-feat-vcd-dvd-all-pal-dvd"> +<title>PAL DVD</title> + +<para> +<screen> +mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=dvd:tsaf \ + -vf scale=720:576,harddup -srate 48000 -af lavcresample=48000 \ + -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:\ +keyint=15:acodec=ac3:abitrate=192:aspect=16/9 -ofps 25 \ + -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> +</screen> +</para> +</sect3> + + +<sect3 id="menc-feat-vcd-dvd-all-ntsc-dvd"> +<title>NTSC DVD</title> + +<para> +<screen> +mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=dvd:tsaf \ + -vf scale=720:480,harddup -srate 48000 -af lavcresample=48000 \ + -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:\ +keyint=18:acodec=ac3:abitrate=192:aspect=16/9 -ofps 30000/1001 \ + -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> +</screen> +</para> +</sect3> + + +<sect3 id="menc-feat-vcd-dvd-all-pal-ac3-copy"> +<title>PAL AVI Containing AC3 Audio to DVD</title> + +<para> +If the source already has AC3 audio, use -oac copy instead of re-encoding it. +<screen> +mencoder -oac copy -ovc lavc -of mpeg -mpegopts format=dvd:tsaf \ + -vf scale=720:576,harddup -ofps 25 \ + -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:\ +keyint=15:aspect=16/9 -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> +</screen> +</para> +</sect3> + + +<sect3 id="menc-feat-vcd-dvd-all-ntsc-ac3-copy"> +<title>NTSC AVI Containing AC3 Audio to DVD</title> + +<para> +If the source already has AC3 audio, and is NTSC @ 24000/1001 fps: +<screen> +mencoder -oac copy -ovc lavc -of mpeg -mpegopts format=dvd:tsaf:telecine \ + -vf scale=720:480,harddup -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:\ + vrc_maxrate=9800:vbitrate=5000:keyint=15:aspect=16/9 -ofps 24000/1001 \ + -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> +</screen> +</para> +</sect3> + + +<sect3 id="menc-feat-vcd-dvd-all-pal-svcd"> +<title>PAL SVCD</title> + +<para> +<screen> +mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xsvcd -vf \ + scale=480:576,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ + vcodec=mpeg2video:mbd=2:keyint=15:vrc_buf_size=917:vrc_minrate=600:\ +vbitrate=2500:vrc_maxrate=2500:acodec=mp2:abitrate=224 -ofps 25 \ + -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> </screen> </para> </sect3> -</sect2> - -<sect2 id="menc-feat-vcd-dvd-all"> -<title>Putting it all Together</title> -<para> - This section shows some complete commands for creating VCD/SVCD/DVD - compliant videos. -</para> - -<sect3 id="menc-feat-vcd-dvd-all-pal-dvd"> -<title>PAL DVD</title> -<para> - <screen> - mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=dvd:tsaf -vf scale=720:576,\ - harddup -srate 48000 -af lavcresample=48000 -lavcopts vcodec=mpeg2video:\ - vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:keyint=15:acodec=ac3:\ - abitrate=192:aspect=16/9 -ofps 25 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> -</para> -</sect3> - -<sect3 id="menc-feat-vcd-dvd-all-ntsc-dvd"> -<title>NTSC DVD</title> -<para> - <screen> - mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=dvd:tsaf -vf scale=720:480,\ - harddup -srate 48000 -af lavcresample=48000 -lavcopts vcodec=mpeg2video:\ - vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:keyint=18:acodec=ac3:\ - abitrate=192:aspect=16/9 -ofps 30000/1001 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> -</para> -</sect3> - -<sect3 id="menc-feat-vcd-dvd-all-pal-ac3-copy"> -<title>PAL AVI Containing AC3 Audio to DVD</title> -<para> - If the source already has AC3 audio, use -oac copy instead of re-encoding it. - <screen> - mencoder -oac copy -ovc lavc -of mpeg -mpegopts format=dvd:tsaf -vf scale=720:576,\ - harddup -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:\ - vbitrate=5000:keyint=15:aspect=16/9 -ofps 25 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> -</para> -</sect3> - -<sect3 id="menc-feat-vcd-dvd-all-ntsc-ac3-copy"> -<title>NTSC AVI Containing AC3 Audio to DVD</title> -<para> - If the source already has AC3 audio, and is NTSC @ 24000/1001 fps: - <screen> - mencoder -oac copy -ovc lavc -of mpeg -mpegopts format=dvd:tsaf:telecine \ - -vf scale=720:480,harddup -lavcopts vcodec=mpeg2video:vrc_buf_size=1835:\ - vrc_maxrate=9800:vbitrate=5000:keyint=15:aspect=16/9 -ofps 24000/1001 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> -</para> -</sect3> - -<sect3 id="menc-feat-vcd-dvd-all-pal-svcd"> -<title>PAL SVCD</title> -<para> - <screen> - mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xsvcd -vf \ - scale=480:576,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ - vcodec=mpeg2video:mbd=2:keyint=15:vrc_buf_size=917:vrc_minrate=600:\ - vbitrate=2500:vrc_maxrate=2500:acodec=mp2:abitrate=224 -ofps 25 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> -</para> -</sect3> <sect3 id="menc-feat-vcd-dvd-all-ntsc-svcd"> <title>NTSC SVCD</title> -<para> - <screen> - mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xsvcd -vf \ - scale=480:480,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ - vcodec=mpeg2video:mbd=2:keyint=18:vrc_buf_size=917:vrc_minrate=600:\ - vbitrate=2500:vrc_maxrate=2500:acodec=mp2:abitrate=224 -ofps 30000/1001 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> + +<para> +<screen> +mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xsvcd -vf \ + scale=480:480,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ + vcodec=mpeg2video:mbd=2:keyint=18:vrc_buf_size=917:vrc_minrate=600:\ +vbitrate=2500:vrc_maxrate=2500:acodec=mp2:abitrate=224 -ofps 30000/1001 \ + -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> +</screen> </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-all-pal-vcd"> <title>PAL VCD</title> -<para> - <screen> - mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xvcd -vf \ - scale=352:288,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ - vcodec=mpeg1video:keyint=15:vrc_buf_size=327:vrc_minrate=1152:vbitrate=1152:\ - vrc_maxrate=1152:acodec=mp2:abitrate=224 -ofps 25 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> + +<para> +<screen> +mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xvcd -vf \ + scale=352:288,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ + vcodec=mpeg1video:keyint=15:vrc_buf_size=327:vrc_minrate=1152:\ +vbitrate=1152:vrc_maxrate=1152:acodec=mp2:abitrate=224 -ofps 25 \ + -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> +</screen> </para> </sect3> + <sect3 id="menc-feat-vcd-dvd-all-ntsc-vcd"> <title>NTSC VCD</title> -<para> - <screen> - mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xvcd -vf \ - scale=352:240,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ - vcodec=mpeg1video:keyint=18:vrc_buf_size=327:vrc_minrate=1152:vbitrate=1152:\ - vrc_maxrate=1152:acodec=mp2:abitrate=224 -ofps 30000/1001 \ - -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> - </screen> + +<para> +<screen> +mencoder -oac lavc -ovc lavc -of mpeg -mpegopts format=xvcd -vf \ + scale=352:240,harddup -srate 44100 -af lavcresample=44100 -lavcopts \ + vcodec=mpeg1video:keyint=18:vrc_buf_size=327:vrc_minrate=1152:\ +vbitrate=1152:vrc_maxrate=1152:acodec=mp2:abitrate=224 -ofps 30000/1001 \ + -o <replaceable>movie.mpg</replaceable> <replaceable>movie.avi</replaceable> +</screen> </para> </sect3> - </sect2> - </sect1> - </chapter>
--- a/DOCS/xml/en/faq.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/faq.xml Fri Dec 08 11:38:06 2006 +0000 @@ -69,6 +69,7 @@ </qandaentry> </qandadiv> +<!-- ********** --> <qandadiv id="faq-compilation-installation"> <title>Compilation and installation</title> @@ -194,6 +195,7 @@ </qandaentry> </qandadiv> +<!-- ********** --> <qandadiv id="faq-general"> <title>General questions</title> @@ -211,11 +213,11 @@ <qandaentry> <question><para> -I've found a nasty bug when I tried to play my favorite video! Who should I inform? +I've found a nasty bug when I tried to play my favorite video! +Who should I inform? </para></question> <answer><para> -Please read the -<link linkend="bugreports">bug reporting guidelines</link> +Please read the <link linkend="bugreports">bug reporting guidelines</link> and follow the instructions. </para></answer> </qandaentry> @@ -226,8 +228,9 @@ </para></question> <answer><para> Check the <ulink url="../../codecs-status.html">codec status</ulink>, -if it doesn't contain your codec, read the <link linkend="codecs">codec documentation</link>, -especially the <link linkend="codec-importing">codec importing HOWTO</link> and contact us. +if it doesn't contain your codec, read the +<link linkend="codecs">codec documentation</link>, especially the +<link linkend="codec-importing">codec importing HOWTO</link> and contact us. </para></answer> </qandaentry> @@ -237,8 +240,8 @@ <screen>Linux RTC init: ioctl (rtc_pie_on): Permission denied</screen> </para></question> <answer><para> -You need a specially set up kernel to use the RTC timing -code. For details see the <link linkend="rtc">RTC</link> section of the documentation. +You need a specially set up kernel to use the RTC timing code. +For details see the <link linkend="rtc">RTC</link> section of the documentation. </para></answer> </qandaentry> @@ -265,46 +268,66 @@ </para></question> <answer><para> Example: -<screen>A: 2.1 V: 2.2 A-V: -0.167 ct: 0.042 57/57 41% 0% 2.6% 0 4 49% 1.00x</screen> +<screen> +A: 2.1 V: 2.2 A-V: -0.167 ct: 0.042 57/57 41% 0% 2.6% 0 4 49% 1.00x +</screen> <variablelist> -<varlistentry><term><systemitem>A: 2.1</systemitem></term> -<listitem><para>audio position in seconds</para></listitem> +<varlistentry> + <term><systemitem>A: 2.1</systemitem></term> + <listitem><para>audio position in seconds</para></listitem> </varlistentry> -<varlistentry><term><systemitem>V: 2.2</systemitem></term> -<listitem><para>video position in seconds</para></listitem> +<varlistentry> + <term><systemitem>V: 2.2</systemitem></term> + <listitem><para>video position in seconds</para></listitem> </varlistentry> -<varlistentry><term><systemitem>A-V: -0.167</systemitem></term> -<listitem><para>audio-video difference in seconds (delay)</para></listitem> +<varlistentry> + <term><systemitem>A-V: -0.167</systemitem></term> + <listitem><para>audio-video difference in seconds (delay)</para></listitem> </varlistentry> -<varlistentry><term><systemitem>ct: 0.042</systemitem></term> -<listitem><para>total A-V sync correction done</para></listitem> +<varlistentry> + <term><systemitem>ct: 0.042</systemitem></term> + <listitem><para>total A-V sync correction done</para></listitem> </varlistentry> -<varlistentry><term><systemitem>57/57</systemitem></term> -<listitem><para>frames played/decoded (counting from last seek)</para></listitem> +<varlistentry> + <term><systemitem>57/57</systemitem></term> + <listitem><para> + frames played/decoded (counting from last seek) + </para></listitem> </varlistentry> -<varlistentry><term><systemitem>41%</systemitem></term> -<listitem><para>video codec CPU usage in percent - (for slice rendering and direct rendering this - includes video_out)</para></listitem> +<varlistentry> + <term><systemitem>41%</systemitem></term> + <listitem><para> + video codec CPU usage in percent + (for slice rendering and direct rendering this includes video_out) + </para></listitem> </varlistentry> -<varlistentry><term><systemitem>0%</systemitem></term> -<listitem><para>video_out CPU usage</para></listitem> +<varlistentry> + <term><systemitem>0%</systemitem></term> + <listitem><para>video_out CPU usage</para></listitem> </varlistentry> -<varlistentry><term><systemitem>2.6%</systemitem></term> -<listitem><para>audio codec CPU usage in percent</para></listitem> +<varlistentry> + <term><systemitem>2.6%</systemitem></term> + <listitem><para>audio codec CPU usage in percent</para></listitem> </varlistentry> -<varlistentry><term><systemitem>0</systemitem></term> -<listitem><para>frames dropped to maintain A-V sync</para></listitem> +<varlistentry> + <term><systemitem>0</systemitem></term> + <listitem><para>frames dropped to maintain A-V sync</para></listitem> +</varlistentry> +<varlistentry> + <term><systemitem>4</systemitem></term> + <listitem><para> + current level of image postprocessing (when using <option>-autoq</option>) + </para></listitem> </varlistentry> -<varlistentry><term><systemitem>4</systemitem></term> -<listitem><para>current level of image postprocessing (when using -<option>-autoq</option>)</para></listitem> +<varlistentry> + <term><systemitem>49%</systemitem></term> + <listitem><para> + current cache size used (around 50% is normal) + </para></listitem> </varlistentry> -<varlistentry><term><systemitem>49%</systemitem></term> -<listitem><para>current cache size used (around 50% is normal)</para></listitem> -</varlistentry> -<varlistentry><term><systemitem>1.00x</systemitem></term> -<listitem><para>playback speed as a factor of original speed</para></listitem> +<varlistentry> + <term><systemitem>1.00x</systemitem></term> + <listitem><para>playback speed as a factor of original speed</para></listitem> </varlistentry> </variablelist> Most of them are for debug purposes, use the <option>-quiet</option> @@ -319,7 +342,8 @@ <qandaentry> <question><para> -There are error messages about file not found <filename>/usr/local/lib/codecs/</filename> ... +There are error messages about file not found +<filename>/usr/local/lib/codecs/</filename> ... </para></question> <answer><para> Download and install the binary codecs from our @@ -345,8 +369,9 @@ slow down playing! I know it's unlikely ... </para></question> <answer><para> -After running <filename>./configure</filename>, edit <filename>config.h</filename> -and replace <systemitem>#undef FAST_OSD</systemitem> with +After running <filename>./configure</filename>, +edit <filename>config.h</filename> and replace +<systemitem>#undef FAST_OSD</systemitem> with <systemitem>#define FAST_OSD</systemitem>. Then recompile. </para></answer> </qandaentry> @@ -372,11 +397,14 @@ </para></question> <answer><para> Use: -<screen>mplayer <replaceable>options</replaceable> <replaceable>filename</replaceable> < /dev/null &</screen> +<screen> +mplayer <replaceable>options</replaceable> <replaceable>filename</replaceable> < /dev/null & +</screen> </para></answer> </qandaentry> </qandadiv> +<!-- ********** --> <qandadiv id="faq-playback"> <title>Playback problems</title> @@ -493,35 +521,32 @@ <para> If you run into this problem you have two options: <itemizedlist> -<listitem><para>Wait two weeks. It might start working again.</para></listitem> -<listitem><para>Relink all the binaries on the system with different -prelink options. Here are step by step instructions:</para> -<para> -<orderedlist> -<listitem><para>Edit <filename>/etc/syconfig/prelink</filename> and change</para> -<para> -<programlisting> -PRELINK_OPTS=-mR -</programlisting> -</para> -<para> -to -<programlisting> -PRELINK_OPTS="-mR --no-exec-shield" -</programlisting> -</para> -</listitem> -<listitem><para><command>touch /var/lib/misc/prelink.force</command></para></listitem> -<listitem><para><command>/etc/cron.daily/prelink</command> -(This relinks all the applications, and it takes -quite a while.)</para></listitem> -<listitem> -<para><command>execstack -s <replaceable>/path/to/</replaceable>mplayer</command> -(This turns off exec-shield for the <application>MPlayer</application> binary.) -</para> -</listitem> -</orderedlist> -</para> +<listitem><para> + Wait two weeks. It might start working again. +</para></listitem> +<listitem><para> + Relink all the binaries on the system with different + prelink options. Here are step by step instructions: + </para> + <procedure> + <step><para> + Edit <filename>/etc/syconfig/prelink</filename> and change + <programlisting>PRELINK_OPTS=-mR</programlisting> to + <programlisting>PRELINK_OPTS="-mR --no-exec-shield"</programlisting> + </para></step> + <step><para> + <command>touch /var/lib/misc/prelink.force</command> + </para></step> + <step><para><command>/etc/cron.daily/prelink</command> + (This relinks all the applications, and it takes + quite a while.) + </para></step> + <step><para> + <command>execstack -s <replaceable>/path/to/</replaceable>mplayer</command> + (This turns off exec-shield for the + <application>MPlayer</application> binary.) + </para></step> + </procedure> </listitem> </itemizedlist> </para></answer> @@ -541,8 +566,8 @@ <qandaentry> <question><para> -When I try to grab from my tuner, it works, but colors are strange. It's OK with other -applications. +When I try to grab from my tuner, it works, but colors are strange. +It's OK with other applications. </para></question> <answer><para> Your card probably reports some colorspaces as supported when in fact @@ -553,21 +578,25 @@ <qandaentry> <question><para> -I get very strange percentage values (way too big) while playing files on my notebook. +I get very strange percentage values (way too big) +while playing files on my notebook. </para></question> <answer><para> It's an effect of the power management / power saving system of your notebook (BIOS, not kernel). Plug the external power connector in -<emphasis role="bold">before</emphasis> you power on your notebook. You can also -try whether <ulink url="http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html">cpufreq</ulink> +<emphasis role="bold">before</emphasis> you power on your notebook. You can +also try whether +<ulink url="http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html">cpufreq</ulink> (a SpeedStep interface for Linux) helps you. </para></answer> </qandaentry> <qandaentry> <question><para> -The audio/video gets totally out of sync when I run <application>MPlayer</application> -as root on my notebook. It works normal when i run it as a user. +The audio/video gets totally out of sync when I run +<application>MPlayer</application> as +<systemitem class="username">root</systemitem> on my notebook. +It works normal when i run it as a user. </para></question> <answer><para> This is again a power management effect (see above). Plug the external power @@ -588,6 +617,7 @@ </qandaentry> </qandadiv> +<!-- ********** --> <qandadiv id="faq-driver"> <title>Video/audio driver problems (vo/ao)</title> @@ -621,13 +651,11 @@ <answer><para> Just change your video output device. Issue the following command to get a list of available video output drivers: -<screen> -mplayer -vo help -</screen> +<screen>mplayer -vo help</screen> After you've chosen the correct video output driver, add it to your configuration file. Add <programlisting> - vo = <replaceable>selected_vo</replaceable> +vo = <replaceable>selected_vo</replaceable> </programlisting> to <filename>~/.mplayer/config</filename> and/or <programlisting> @@ -664,7 +692,8 @@ <qandaentry> <question><para> My computer plays MS DivX AVIs with resolutions ~ 640x300 and stereo MP3 sound -too slow. When I use the <option>-nosound</option> option, everything is OK (but quiet). +too slow. +When I use the <option>-nosound</option> option, everything is OK (but quiet). </para></question> <answer><para> Your machine is too slow or your sound card driver is broken. Consult the @@ -688,17 +717,18 @@ <question><para> I have no sound when playing a video and get error messages similar to this one: <screen> - AO: [oss] 44100Hz 2ch Signed 16-bit (Little-Endian) - audio_setup: Can't open audio device /dev/dsp: Device or resource busy - couldn't open/init audio device -> NOSOUND - Audio: no sound!!! - Start playing... +AO: [oss] 44100Hz 2ch Signed 16-bit (Little-Endian) +audio_setup: Can't open audio device /dev/dsp: Device or resource busy +couldn't open/init audio device -> NOSOUND +Audio: no sound!!! +Start playing... </screen> </para></question> <answer><para> Are you running KDE or GNOME with the aRts or ESD sound daemon? Try disabling -the sound daemon or use the <option>-ao arts</option> or <option>-ao esd</option> -option to make <application>MPlayer</application> use aRts or ESD. +the sound daemon or use the <option>-ao arts</option> or +<option>-ao esd</option> option to make <application>MPlayer</application> use +aRts or ESD. You might also be running ALSA without OSS emulation, try loading the ALSA OSS kernel modules or add <option>-ao alsa</option> to your command line to directly use the ALSA audio output driver. @@ -722,7 +752,8 @@ <qandaentry> <question><para> -I have A/V sync problems. Some of my AVIs play fine, but some play with double speed! +I have A/V sync problems. +Some of my AVIs play fine, but some play with double speed! </para></question> <answer><para> You have a buggy sound card/driver. Most likely it's fixed at 44100Hz, and you @@ -733,26 +764,29 @@ <qandaentry> <question><para> -When I play this movie I get video-audio desync and/or <application>MPlayer</application> -crashes with the following message: -<screen>DEMUXER: Too many (945 in 8390980 bytes) video packets in the buffer!</screen> +When I play this movie I get video-audio desync and/or +<application>MPlayer</application> crashes with the following message: +<screen> +DEMUXER: Too many (945 in 8390980 bytes) video packets in the buffer! +</screen> </para></question> <answer><para> This can have multiple reasons. <itemizedlist> <listitem><para> -Your CPU <emphasis>and/or</emphasis> video card <emphasis>and/or</emphasis> -bus is too slow. <application>MPlayer</application> displays a message if -this is the case (and the dropped frames counter goes up fast). + Your CPU <emphasis>and/or</emphasis> video card <emphasis>and/or</emphasis> + bus is too slow. <application>MPlayer</application> displays a message if + this is the case (and the dropped frames counter goes up fast). </para></listitem> <listitem><para> -If it is an AVI, maybe it has bad interleaving, try the -<option>-ni</option> to work around this. -Or it may have a bad header, in this case <option>-nobps</option> -and/or <option>-mc 0</option> can help. + If it is an AVI, maybe it has bad interleaving, try the + <option>-ni</option> to work around this. + Or it may have a bad header, in this case <option>-nobps</option> + and/or <option>-mc 0</option> can help. </para></listitem> <listitem><para> -Your sound driver is buggy. See the <link linkend="audio">audio section</link>. + Your sound driver is buggy. + See the <link linkend="audio">audio section</link>. </para></listitem> </itemizedlist> </para></answer> @@ -760,7 +794,8 @@ <qandaentry> <question><para> -How can I get rid of A/V desynchronization while seeking through RealMedia streams? +How can I get rid of A/V desynchronization +while seeking through RealMedia streams? </para></question> <answer><para> <option>-mc 0.1</option> can help. @@ -768,6 +803,7 @@ </qandaentry> </qandadiv> +<!-- ********** --> <qandadiv id="faq-dvd"> <title>DVD playback</title> @@ -817,7 +853,8 @@ How can I set the region code of my DVD-drive? I don't have Windows! </para></question> <answer><para> -Use the <ulink url="http://linvdr.org/projects/regionset/">regionset tool</ulink>. +Use the +<ulink url="http://linvdr.org/projects/regionset/">regionset tool</ulink>. </para></answer> </qandaentry> @@ -856,8 +893,8 @@ </para></question> <answer><para> Use the <option>-cache</option> option (described in the man page) and try -enabling DMA for the DVD drive with the <command>hdparm</command> tool (described -in the <link linkend="drives">CD chapter</link>). +enabling DMA for the DVD drive with the <command>hdparm</command> tool +(described in the <link linkend="drives">CD chapter</link>). </para></answer> </qandaentry> @@ -881,9 +918,9 @@ <qandaentry> <question><para> -If <application>MPlayer</application> is paused and I try to seek or press any key at all, -<application>MPlayer</application> ceases to be paused. I would like to be able -to seek in the paused movie. +If <application>MPlayer</application> is paused and I try to seek or press any +key at all, <application>MPlayer</application> ceases to be paused. +I would like to be able to seek in the paused movie. </para></question> <answer><para> This is very tricky to implement without losing A/V synchronization. @@ -904,6 +941,7 @@ </qandaentry> </qandadiv> +<!-- ********** --> <qandadiv id="faq-encoding"> <title>Encoding</title> @@ -939,8 +977,9 @@ How can I create (S)VCDs automatically? </para></question> <answer><para> -Try the <filename>mencvcd</filename> script from the <filename class="directory">TOOLS</filename> -subdirectory. With it you can encode DVDs or other movies to VCD or SVCD format +Try the <filename>mencvcd</filename> script from the +<filename class="directory">TOOLS</filename> subdirectory. +With it you can encode DVDs or other movies to VCD or SVCD format and even burn them directly to CD. </para></answer> </qandaentry> @@ -1051,7 +1090,8 @@ How can I encode only selected chapters from a DVD? </para></question> <answer><para> -Use the <option>-chapter</option> option correctly, like: <option>-chapter 5-7</option>. +Use the <option>-chapter</option> option correctly, +like: <option>-chapter 5-7</option>. </para></answer> </qandaentry> @@ -1066,36 +1106,48 @@ <qandaentry> <question><para> -What is the meaning of the numbers on the status line during the encoding process? +What is the meaning of the numbers on the status line +during the encoding process? </para></question> <answer><para> Example: -<screen>Pos: 264.5s 6612f ( 2%) 7.12fps Trem: 576min 2856mb A-V:0.065 [2126:192]</screen> +<screen> +Pos: 264.5s 6612f ( 2%) 7.12fps Trem: 576min 2856mb A-V:0.065 [2126:192] +</screen> <variablelist> -<varlistentry><term><systemitem>Pos: 264.5s</systemitem></term> -<listitem><para>time position in the encoded stream</para></listitem> + <varlistentry> + <term><systemitem>Pos: 264.5s</systemitem></term> + <listitem><para>time position in the encoded stream</para></listitem> </varlistentry> -<varlistentry><term><systemitem>6612f</systemitem></term> -<listitem><para>number of video frames encoded</para></listitem> +<varlistentry> + <term><systemitem>6612f</systemitem></term> + <listitem><para>number of video frames encoded</para></listitem> </varlistentry> -<varlistentry><term><systemitem>( 2%)</systemitem></term> -<listitem><para>portion of the input stream encoded</para></listitem> +<varlistentry> + <term><systemitem>( 2%)</systemitem></term> + <listitem><para>portion of the input stream encoded</para></listitem> </varlistentry> -<varlistentry><term><systemitem>7.12fps</systemitem></term> -<listitem><para>encoding speed</para></listitem> +<varlistentry> + <term><systemitem>7.12fps</systemitem></term> + <listitem><para>encoding speed</para></listitem> </varlistentry> -<varlistentry><term><systemitem>Trem: 576min</systemitem></term> -<listitem><para>estimated remaining encoding time</para></listitem> +<varlistentry> + <term><systemitem>Trem: 576min</systemitem></term> + <listitem><para>estimated remaining encoding time</para></listitem> </varlistentry> -<varlistentry><term><systemitem>2856mb</systemitem></term> -<listitem><para>estimated size of the final encode</para></listitem> +<varlistentry> + <term><systemitem>2856mb</systemitem></term> + <listitem><para>estimated size of the final encode</para></listitem> </varlistentry> -<varlistentry><term><systemitem>A-V:0.065</systemitem></term> -<listitem><para>current delay between audio and video streams</para></listitem> +<varlistentry> + <term><systemitem>A-V:0.065</systemitem></term> + <listitem><para>current delay between audio and video streams</para></listitem> </varlistentry> -<varlistentry><term><systemitem>[2126:192]</systemitem></term> -<listitem> -<para>average video bitrate (in kb/s) and average audio bitrate (in kb/s)</para></listitem> +<varlistentry> + <term><systemitem>[2126:192]</systemitem></term> + <listitem><para> + average video bitrate (in kb/s) and average audio bitrate (in kb/s) + </para></listitem> </varlistentry> </variablelist> </para></answer> @@ -1103,7 +1155,8 @@ <qandaentry> <question><para> -Why is the recommended bitrate printed by <application>MEncoder</application> negative? +Why is the recommended bitrate printed by <application>MEncoder</application> +negative? </para></question> <answer><para> Because the bitrate you encoded the audio with is too large to fit the @@ -1140,10 +1193,10 @@ <emphasis role="bold">&</emphasis> at the end of <command>mplayer</command> command): <screen> - mkfifo encode - mplayer -ao pcm -aofile encode dvd://1 & - lame <replaceable>your_opts</replaceable> encode music.mp3 - rm encode +mkfifo <replaceable>encode</replaceable> +mplayer -ao pcm -aofile <replaceable>encode</replaceable> dvd://1 & +lame <replaceable>your_opts</replaceable> <replaceable>encode</replaceable> <replaceable>music.mp3</replaceable> +rm <replaceable>encode</replaceable> </screen> This allows you to use any encoder, not only <application>LAME</application>, just replace <command>lame</command> with your favorite audio encoder in the @@ -1173,7 +1226,7 @@ <option>-ffourcc</option> option. You may also change the FourCC of existing files in the same way: <screen> - mencoder <replaceable>input.avi</replaceable> -o <replaceable>output.avi</replaceable> -ffourcc XVID +mencoder <replaceable>input.avi</replaceable> -o <replaceable>output.avi</replaceable> -ffourcc XVID </screen> Note that this will set the FourCC to XVID rather than DIVX. This is recommended as DIVX FourCC means DivX4, which is a very basic
--- a/DOCS/xml/en/history.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/history.xml Fri Dec 08 11:38:06 2006 +0000 @@ -15,100 +15,173 @@ problems too. So I've decided to write/modify one... </para></blockquote><para>A'rpi, 2001</para> +<itemizedlist> +<listitem> <para> -<itemizedlist> -<listitem><para> - <emphasis role="bold"><application>mpg12play</application> v0.1-v0.3</emphasis>: Sep 22-25, 2000 - </para> - <para>The first try, hacked together in a half hour! I've used libmpeg3 - from <ulink url="http://www.heroinewarrior.com"/> up to the version 0.3, but - there were image quality and speed problems with it. - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>mpg12play</application> v0.5-v0.87</emphasis>: Sep 28-Oct 20, 2000 - </para><para>MPEG codec replaced with DVDview by Dirk Farin, it was a - great stuff, but it was slow and was written in C++ (A'rpi hates C++!!!) - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>mpg12play</application> v0.9-v0.95pre5</emphasis>: Oct 21-Nov 2, 2000 - </para><para>MPEG codec was libmpeg2 (mpeg2dec) by Aaron Holtzman and - Michel Lespinasse. It's great, optimized very fast C code with perfect - image quality and 100% MPEG standard conformance. - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> v0.3-v0.9</emphasis>: Nov 18-Dec 4, 2000 - </para><para>It was a pack of two programs: mpg12play v0.95pre6 and my - new simple AVI player 'avip' based on avifile's Win32 DLL loader. - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> v0.10</emphasis>: Jan 1, 2001 - </para><para>The MPEG and AVI player in a single binary! - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> v0.11pre series</emphasis>: - </para><para>Some new developers joined and since 0.11 the <application>MPlayer</application> - project is a team-work! Added ASF file support, and OpenDivX - (see <ulink url="http://www.projectmayo.com"/>) en/decoding. - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> v0.17a "The IdegCounter"</emphasis> Apr 27, 2001 - </para><para>The release version of the 0.11pre after 4 months of heavy - development! Try it, and be amazed! Thousands of new features added... - and of course old code was improved too, bugs removed etc. - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 0.18 "The BugCounter"</emphasis> Jul 9, 2001 - </para><para>2 months since 0.17 and here's a new release.. Completed ASF - support, more subtitle formats, introduced libao (similar to libvo but to - audio), even more stable than ever, and so on. It's a MUST! - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 0.50 "The Faszom(C)ounter"</emphasis> Oct 8, 2001 - </para><para>Hmm. Release again. Tons of new features, beta GUI version, - bugs fixed, new vo and ao drivers, ported to many systems, including - opensource DivX codecs and much more. Try it! - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 0.60 "The RTFMCounter"</emphasis> Jan 3, 2002 - </para><para>MOV/VIVO/RM/FLI/NUV fileformats support, native CRAM, Cinepak, - ADPCM codecs, and support for XAnim's binary codecs; DVD subtitles support, - first release of <application>MEncoder</application>, TV grabbing, cache, - liba52, countless fixes. - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 0.90pre10 "The BirthdayCounter"</emphasis> Nov 11, 2002 - </para><para> Although this is not a release, I am going to mention it because it - came out 2 years after <application>MPlayer</application> v0.01. - Happy birthday, <application>MPlayer</application>! - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 0.90rc1 "The CodecCounter"</emphasis> Dec 7, 2002 - </para><para>Again not a release, but after adding Sorenson 3 (QuickTime) - and Windows Media 9 support, <application>MPlayer</application> is the - world's first movie player with support for all known video formats! - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 0.90 "The CounterCounter"</emphasis> Apr 6, 2003 - </para><para>After more than 1 year, we finally concluded that the code was indeed - stable again, and ready to be published as a release. Unfortunately we - forgot even to increase the version number, and other annoying bugs went - in, so get ready for... - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 0.91</emphasis> Aug 13, 2003 - </para><para>The above mentioned and lot of other bugs have been fixed. - This is the latest stable version. - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 1.0pre1 "Development on the beach"</emphasis> Sep 1, 2003 - </para><para>Although this is not a stable release, I am going to mention - it because it is the first pre version of the 1.0 series of <application>MPlayer</application> - and it is intended to help the <emphasis>big bug hunting party</emphasis>. - This is a huge step forward! - </para></listitem> -<listitem><para> - <emphasis role="bold"><application>MPlayer</application> 1.0</emphasis> date yet unknown - </para></listitem> +<emphasis role="bold"><application>mpg12play</application> v0.1-v0.3</emphasis>: Sep 22-25, 2000 +</para> +<para> +The first try, hacked together in a half hour! I've used libmpeg3 +from <ulink url="http://www.heroinewarrior.com"/> up to the version 0.3, but +there were image quality and speed problems with it. +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>mpg12play</application> v0.5-v0.87</emphasis>: Sep 28-Oct 20, 2000 +</para> +<para> +MPEG codec replaced with DVDview by Dirk Farin, it was a +great stuff, but it was slow and was written in C++ (A'rpi hates C++!!!) +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>mpg12play</application> v0.9-v0.95pre5</emphasis>: Oct 21-Nov 2, 2000 +</para> +<para> +MPEG codec was libmpeg2 (mpeg2dec) by Aaron Holtzman and +Michel Lespinasse. It's great, optimized very fast C code with perfect +image quality and 100% MPEG standard conformance. +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> v0.3-v0.9</emphasis>: Nov 18-Dec 4, 2000 +</para> +<para> +It was a pack of two programs: mpg12play v0.95pre6 and my +new simple AVI player 'avip' based on avifile's Win32 DLL loader. +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> v0.10</emphasis>: Jan 1, 2001 +</para> +<para>The MPEG and AVI player in a single binary! +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> v0.11pre series</emphasis>: +</para> +<para> +Some new developers joined and since 0.11 the <application>MPlayer</application> +project is a team-work! Added ASF file support, and OpenDivX +(see <ulink url="http://www.projectmayo.com"/>) en/decoding. +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> v0.17a "The IdegCounter"</emphasis>: Apr 27, 2001 +</para> +<para> +The release version of the 0.11pre after 4 months of heavy +development! Try it, and be amazed! Thousands of new features added... +and of course old code was improved too, bugs removed etc. +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 0.18 "The BugCounter"</emphasis>: Jul 9, 2001 +</para> +<para> +2 months since 0.17 and here's a new release.. Completed ASF +support, more subtitle formats, introduced libao (similar to libvo but to +audio), even more stable than ever, and so on. It's a MUST! +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 0.50 "The Faszom(C)ounter"</emphasis>: Oct 8, 2001 +</para> +<para> +Hmm. Release again. Tons of new features, beta GUI version, +bugs fixed, new vo and ao drivers, ported to many systems, including +opensource DivX codecs and much more. Try it! +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 0.60 "The RTFMCounter"</emphasis>: Jan 3, 2002 +</para> +<para> +MOV/VIVO/RM/FLI/NUV fileformats support, native CRAM, Cinepak, +ADPCM codecs, and support for XAnim's binary codecs; DVD subtitles support, +first release of <application>MEncoder</application>, TV grabbing, cache, +liba52, countless fixes. +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 0.90pre10 "The BirthdayCounter"</emphasis> Nov 11, 2002 +</para> +<para> +Although this is not a release, I am going to mention it because it +came out 2 years after <application>MPlayer</application> v0.01. +Happy birthday, <application>MPlayer</application>! +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 0.90rc1 "The CodecCounter"</emphasis> Dec 7, 2002 +</para> +<para> +Again not a release, but after adding Sorenson 3 (QuickTime) +and Windows Media 9 support, <application>MPlayer</application> is the +world's first movie player with support for all known video formats! +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 0.90 "The CounterCounter"</emphasis> Apr 6, 2003 +</para> +<para> +After more than 1 year, we finally concluded that the code was indeed +stable again, and ready to be published as a release. Unfortunately we +forgot even to increase the version number, and other annoying bugs went +in, so get ready for... +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 0.91</emphasis> Aug 13, 2003 +</para> +<para> +The above mentioned and lot of other bugs have been fixed. +This is the latest stable version. +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 1.0pre1 "Development on the beach"</emphasis> Sep 1, 2003 +</para> +<para> +Although this is not a stable release, I am going to mention it because it is +the first pre version of the 1.0 series of <application>MPlayer</application> +and it is intended to help the <emphasis>big bug hunting party</emphasis>. +This is a huge step forward! +</para> +</listitem> + +<listitem> +<para> +<emphasis role="bold"><application>MPlayer</application> 1.0</emphasis> date yet unknown +</para> +</listitem> </itemizedlist> -</para> </appendix>
--- a/DOCS/xml/en/install.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/install.xml Fri Dec 08 11:38:06 2006 +0000 @@ -17,6 +17,10 @@ answers. </para> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="softreq"> <title>Software requirements</title> @@ -29,63 +33,66 @@ <emphasis role="bold">gcc</emphasis> - recommended versions are 2.95 and 3.4+. 2.96 and 3.0.x are known to generate faulty code, 3.1 and 3.2 also had problems, 3.3 some minor ones. On PowerPC, use 4.x. - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">Xorg/XFree86</emphasis> - recommended version is 4.3 or later. Make sure the <emphasis role="bold">development packages</emphasis> are installed, too, otherwise it won't work. You don't absolutely need X, some video output drivers work without it. - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">make</emphasis> - recommended version is 3.79.x or later. To build the XML documentation you need 3.80. - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">FreeType</emphasis> - optional, required to have a font for the OSD and subtitles. At least 2.0.9 is required. - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">libjpeg</emphasis> - optional JPEG en/decoder, required for the JPEG video output driver and decoding MJPEG video - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">libpng</emphasis> - optional (M)PNG en/decoder, required for the GUI and the PNG video output driver - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">lame</emphasis> - 3.90 or later is recommended, necessary for encoding MP3 audio with <application>MEncoder</application>. - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">zlib</emphasis> - recommended, necessary for compressed MOV header and PNG support - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold"><ulink url="http://www.live555.com/mplayer/">LIVE555 Streaming Media</ulink></emphasis> - optional, needed for some RTSP/RTP streams - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">directfb</emphasis> - optional, use 0.9.13 or later. - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">cdparanoia</emphasis> - optional, for CDDA support - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">libxmms</emphasis> - optional, for XMMS input plugin support. At least 1.2.7 is required. - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">libsmb</emphasis> - optional, for smb networking support - </para></listitem> +</para></listitem> <listitem><para> <emphasis role="bold">ALSA</emphasis> - optional, for ALSA audio output support. At least 0.9.0rc4 is required. - </para></listitem> +</para></listitem> </itemizedlist> </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="features"> <title>Features</title> @@ -93,26 +100,28 @@ <listitem><para> Decide if you need GUI. If you do, see the <link linkend="gui">GUI</link> section before compiling. - </para></listitem> +</para></listitem> <listitem><para> If you want to install <application>MEncoder</application> (our great all-purpose encoder), see the <link linkend="mencoder"><application>MEncoder</application></link> section. - </para></listitem> +</para></listitem> <listitem><para> If you have a V4L compatible <emphasis role="bold">TV tuner</emphasis> card, - and wish to watch/grab and encode movies with <application>MPlayer</application>, + and wish to watch/grab and encode movies with + <application>MPlayer</application>, read the <link linkend="tv-input">TV input</link> section. - </para></listitem> +</para></listitem> <listitem><para> - If you have a V4L compatible <emphasis role="bold">radio tuner</emphasis> card, - and wish to listen and capture sound with <application>MPlayer</application>, + If you have a V4L compatible <emphasis role="bold">radio tuner</emphasis> + card, and wish to listen and capture sound with + <application>MPlayer</application>, read the <link linkend="radio">radio</link> section. - </para></listitem> +</para></listitem> <listitem><para> There is a neat <emphasis role="bold">OSD Menu</emphasis> support ready to be used. Check the <link linkend="subosd">OSD menu</link> section. - </para></listitem> +</para></listitem> </itemizedlist> <para> @@ -120,7 +129,8 @@ <screen> ./configure make -make install</screen> +make install +</screen> </para> <para> @@ -141,12 +151,11 @@ <filename>codecs.conf</filename> will be ignored completely. Do not do this unless you want to fiddle with <application>MPlayer</application> internals as this can can cause many problems. If you want to change the codecs -search order, use the <option>-vc</option>, <option>-ac</option>, <option>-vfm</option>, -or <option>-afm</option> options either on the command line or in your -config file (see the manual page). +search order, use the <option>-vc</option>, <option>-ac</option>, +<option>-vfm</option>, or <option>-afm</option> options either on the command +line or in your config file (see the manual page). </para> - <para> Debian users can build a .deb package for themselves, it's very simple. Just exec @@ -173,18 +182,20 @@ font file and telling <application>MPlayer</application> to use it. See the <link linkend="subosd">Subtitles and OSD</link> section for details. </para> - </sect1> -<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="gui"> <title>What about the GUI?</title> <para> The GUI needs GTK 1.2.x or GTK 2.0 (it isn't fully GTK, but the panels are). -The skins are stored in PNG format, so GTK, <systemitem class="library">libpng</systemitem> -(and their devel stuff, usually called <systemitem class="library">gtk-dev</systemitem> +The skins are stored in PNG format, so GTK, +<systemitem class="library">libpng</systemitem> (and their devel stuff, usually +called <systemitem class="library">gtk-dev</systemitem> and <systemitem class="library">libpng-dev</systemitem>) has to be installed. You can build it by specifying <option>--enable-gui</option> during <filename>./configure</filename>. Then, to turn on GUI mode, you have to @@ -207,7 +218,9 @@ </para> </sect1> -<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="fonts-osd"> <title>Fonts and OSD</title> @@ -220,6 +233,7 @@ encodings. </para> +<!-- ********** --> <sect2 id="truetype-fonts"> <title>TrueType fonts</title> @@ -253,6 +267,7 @@ </para> </sect2> +<!-- ********** --> <sect2 id="bitmap-fonts"> <title>bitmap fonts</title> @@ -284,15 +299,16 @@ file the same name as your video file with a <filename>.utf</filename> extension and have it in the same directory as the video file. </para> - </sect2> +<!-- ********** --> <sect2 id="osdmenu"> <title>OSD menu</title> <para> -<application>MPlayer</application> has a completely user definiable OSD Menu interface. +<application>MPlayer</application> has a completely user definiable +OSD Menu interface. </para> <note><simpara> @@ -302,56 +318,60 @@ <orderedlist> <title>Installation</title> <listitem><simpara> - compile <application>MPlayer</application> by passing the <option>--enable-menu</option> - to <filename>./configure</filename> - </simpara></listitem> + compile <application>MPlayer</application> by passing the + <option>--enable-menu</option> to <filename>./configure</filename> +</simpara></listitem> <listitem><simpara> make sure you have an OSD font installed - </simpara></listitem> +</simpara></listitem> <listitem><simpara> copy <filename>etc/menu.conf</filename> to your <filename class="directory">.mplayer</filename> directory - </simpara></listitem> +</simpara></listitem> <listitem><simpara> copy <filename>etc/input.conf</filename> to your - <filename class="directory">.mplayer</filename> directory, or to the system-wide - <application>MPlayer</application> config dir (default: + <filename class="directory">.mplayer</filename> directory, or to the + system-wide <application>MPlayer</application> config dir (default: <filename class="directory">/usr/local/etc/mplayer</filename>) - </simpara></listitem> +</simpara></listitem> <listitem><simpara> check and edit <filename>input.conf</filename> to enable menu movement keys (it is described there). - </simpara></listitem> +</simpara></listitem> <listitem><para> start <application>MPlayer</application> by the following example: <screen>$ mplayer -menu <replaceable>file.avi</replaceable></screen> </para></listitem> <listitem><simpara> push any menu key you defined - </simpara></listitem> +</simpara></listitem> </orderedlist> - </sect2> </sect1> -<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="rtc"> <title>RTC</title> + <para> There are three timing methods in <application>MPlayer</application>. <itemizedlist> <listitem><simpara> -<emphasis role="bold">To use the old method</emphasis>, you don't have to do + <emphasis role="bold">To use the old method</emphasis>, you don't have to do anything. It uses <systemitem>usleep()</systemitem> to tune A/V sync, with +/- 10ms accuracy. However sometimes the sync has to be tuned even finer. - </simpara></listitem> -<listitem><para> -<emphasis role="bold">The new timer</emphasis> code uses the RTC (RealTime Clock) - for this task, because it has precise 1ms timers. The <option>-rtc</option> - option enables it, but a properly set up kernel is required. +</simpara></listitem> +<listitem> + <para> + <emphasis role="bold">The new timer</emphasis> code uses the RTC (RealTime + Clock) for this task, because it has precise 1ms timers. + The <option>-rtc</option> option enables it, + but a properly set up kernel is required. If you are running kernel 2.4.19pre8 or later you can adjust the maximum RTC frequency for normal users through the <systemitem class="systemname">/proc </systemitem> filesystem. Use one of the following two commands to @@ -362,19 +382,20 @@ <filename>/etc/sysctl.conf</filename>. </para> <para> - You can see the new timer's efficiency in the status line. - The power management functions of some notebook BIOSes with speedstep CPUs - interact badly with RTC. Audio and video may get out of sync. Plugging the - external power connector in before you power up your notebook seems to help. - In some hardware combinations (confirmed during usage of non-DMA DVD drive - on an ALi1541 board) usage of the RTC timer causes skippy playback. It's - recommended to use the third method in these cases. - </para></listitem> -<listitem><simpara> + You can see the new timer's efficiency in the status line. + The power management functions of some notebook BIOSes with speedstep CPUs + interact badly with RTC. Audio and video may get out of sync. Plugging the + external power connector in before you power up your notebook seems to help. + In some hardware combinations (confirmed during usage of non-DMA DVD drive + on an ALi1541 board) usage of the RTC timer causes skippy playback. It's + recommended to use the third method in these cases. + </para> +</listitem> +<listitem><para> <emphasis role="bold">The third timer code</emphasis> is turned on with the <option>-softsleep</option> option. It has the efficiency of the RTC, but it doesn't use RTC. On the other hand, it requires more CPU. - </simpara></listitem> +</para></listitem> </itemizedlist> </para> </sect1>
--- a/DOCS/xml/en/mencoder.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/mencoder.xml Fri Dec 08 11:38:06 2006 +0000 @@ -39,35 +39,35 @@ <row><entry>Audio codec name</entry><entry>Description</entry></row> </thead> <tbody> - <row> - <entry>mp3lame</entry> - <entry>encode to VBR, ABR or CBR MP3 with LAME</entry> - </row> - <row> - <entry>lavc</entry> - <entry>use one of <link linkend="menc-feat-enc-libavcodec-audio-codecs"><systemitem class="library">libavcodec</systemitem>'s audio codecs</link> - </entry> - </row> - <row> - <entry>faac</entry> - <entry>FAAC AAC audio encoder</entry> - </row> - <row> - <entry>toolame</entry> - <entry>MPEG Audio Layer 2 encoder</entry> - </row> - <row> - <entry>twolame</entry> - <entry>MPEG Audio Layer 2 encoder based on tooLAME</entry> - </row> - <row> - <entry>pcm</entry> - <entry>uncompressed PCM audio</entry> - </row> - <row> - <entry>copy</entry> - <entry>do not reencode, just copy compressed frames</entry> - </row> +<row> + <entry>mp3lame</entry> + <entry>encode to VBR, ABR or CBR MP3 with LAME</entry> +</row> +<row> + <entry>lavc</entry> + <entry>use one of <link linkend="menc-feat-enc-libavcodec-audio-codecs"><systemitem class="library">libavcodec</systemitem>'s audio codecs</link> + </entry> +</row> +<row> + <entry>faac</entry> + <entry>FAAC AAC audio encoder</entry> +</row> +<row> + <entry>toolame</entry> + <entry>MPEG Audio Layer 2 encoder</entry> +</row> +<row> + <entry>twolame</entry> + <entry>MPEG Audio Layer 2 encoder based on tooLAME</entry> +</row> +<row> + <entry>pcm</entry> + <entry>uncompressed PCM audio</entry> +</row> +<row> + <entry>copy</entry> + <entry>do not reencode, just copy compressed frames</entry> +</row> </tbody> </tgroup> </informaltable> @@ -81,35 +81,35 @@ <row><entry>Video codec name</entry><entry>Description</entry></row> </thead> <tbody> - <row> - <entry>lavc</entry> - <entry>use one of <link linkend="menc-feat-enc-libavcodec-video-codecs"><systemitem class="library">libavcodec</systemitem>'s video codecs</link> - </entry> - </row> - <row> - <entry>xvid</entry> - <entry>Xvid, MPEG-4 Advanced Simple Profile (ASP) codec</entry> - </row> - <row> - <entry>x264</entry> - <entry>x264, MPEG-4 Advanced Video Coding (AVC), AKA H.264 codec</entry> - </row> - <row> - <entry>nuv</entry> - <entry>nuppel video, used by some realtime applications</entry> - </row> - <row> - <entry>raw</entry> - <entry>uncompressed video frames</entry> - </row> - <row> - <entry>copy</entry> - <entry>do not reencode, just copy compressed frames</entry> - </row> - <row> - <entry>frameno</entry> - <entry>used for 3-pass encoding (not recommended)</entry> - </row> +<row> + <entry>lavc</entry> + <entry>use one of <link linkend="menc-feat-enc-libavcodec-video-codecs"><systemitem class="library">libavcodec</systemitem>'s video codecs</link> + </entry> +</row> +<row> + <entry>xvid</entry> + <entry>Xvid, MPEG-4 Advanced Simple Profile (ASP) codec</entry> +</row> +<row> + <entry>x264</entry> + <entry>x264, MPEG-4 Advanced Video Coding (AVC), AKA H.264 codec</entry> +</row> +<row> + <entry>nuv</entry> + <entry>nuppel video, used by some realtime applications</entry> +</row> +<row> + <entry>raw</entry> + <entry>uncompressed video frames</entry> +</row> +<row> + <entry>copy</entry> + <entry>do not reencode, just copy compressed frames</entry> +</row> +<row> + <entry>frameno</entry> + <entry>used for 3-pass encoding (not recommended)</entry> +</row> </tbody> </tgroup> </informaltable> @@ -133,27 +133,27 @@ <row><entry>Container format name</entry><entry>Description</entry></row> </thead> <tbody> - <row> - <entry>lavf</entry> - <entry>one of the containers supported by - <systemitem class="library">libavformat</systemitem></entry> - </row> - <row> - <entry>avi</entry> - <entry>Audio-Video Interleaved</entry> - </row> - <row> - <entry>mpeg</entry> - <entry>MPEG-1 and MPEG-2 PS</entry> - </row> - <row> - <entry>rawvideo</entry> - <entry>raw video stream (no muxing - one video stream only)</entry> - </row> - <row> - <entry>rawaudio</entry> - <entry>raw audio stream (no muxing - one audio stream only)</entry> - </row> +<row> + <entry>lavf</entry> + <entry>one of the containers supported by + <systemitem class="library">libavformat</systemitem></entry> +</row> +<row> + <entry>avi</entry> + <entry>Audio-Video Interleaved</entry> +</row> +<row> + <entry>mpeg</entry> + <entry>MPEG-1 and MPEG-2 PS</entry> +</row> +<row> + <entry>rawvideo</entry> + <entry>raw video stream (no muxing - one video stream only)</entry> +</row> +<row> + <entry>rawaudio</entry> + <entry>raw audio stream (no muxing - one audio stream only)</entry> +</row> </tbody> </tgroup> </informaltable> @@ -185,54 +185,54 @@ <entry>Description</entry> </row></thead> <tbody> - <row> - <entry>mpg</entry> - <entry>MPEG-1 and MPEG-2 PS</entry> - </row> - <row> - <entry>asf</entry> - <entry>Advanced Streaming Format</entry> - </row> - <row> - <entry>avi</entry> - <entry>Audio-Video Interleaved</entry> - </row> - <row> - <entry>wav</entry> - <entry>Waveform Audio</entry> - </row> - <row> - <entry>swf</entry> - <entry>Macromedia Flash</entry> - </row> - <row> - <entry>flv</entry> - <entry>Macromedia Flash video</entry> - </row> - <row> - <entry>rm</entry> - <entry>RealMedia</entry> - </row> - <row> - <entry>au</entry> - <entry>SUN AU</entry> - </row> - <row> - <entry>nut</entry> - <entry>NUT open container (experimental and not yet spec-compliant)</entry> - </row> - <row> - <entry>mov</entry> - <entry>QuickTime</entry> - </row> - <row> - <entry>mp4</entry> - <entry>MPEG-4 format</entry> - </row> - <row> - <entry>dv</entry> - <entry>Sony Digital Video container</entry> - </row> +<row> + <entry>mpg</entry> + <entry>MPEG-1 and MPEG-2 PS</entry> +</row> +<row> + <entry>asf</entry> + <entry>Advanced Streaming Format</entry> +</row> +<row> + <entry>avi</entry> + <entry>Audio-Video Interleaved</entry> +</row> +<row> + <entry>wav</entry> + <entry>Waveform Audio</entry> +</row> +<row> + <entry>swf</entry> + <entry>Macromedia Flash</entry> +</row> +<row> + <entry>flv</entry> + <entry>Macromedia Flash video</entry> +</row> +<row> + <entry>rm</entry> + <entry>RealMedia</entry> +</row> +<row> + <entry>au</entry> + <entry>SUN AU</entry> +</row> +<row> + <entry>nut</entry> + <entry>NUT open container (experimental and not yet spec-compliant)</entry> +</row> +<row> + <entry>mov</entry> + <entry>QuickTime</entry> +</row> +<row> + <entry>mp4</entry> + <entry>MPEG-4 format</entry> +</row> +<row> + <entry>dv</entry> + <entry>Sony Digital Video container</entry> +</row> </tbody> </tgroup> </informaltable> @@ -247,8 +247,8 @@ <application>MPlayer</application>. </para> -<informalexample> -<para>Example:</para> +<example> +<title>encode to Macromedia Flash format</title> <para> Creating a Macromedia Flash video suitable for playback in a web browser with the Macromedia Flash plugin: @@ -258,7 +258,7 @@ -lavcopts vcodec=flv:vbitrate=500:mbd=2:mv0:trell:v4mv:cbp:last_pred=3 </screen> </para> -</informalexample> +</example> </sect1> @@ -318,11 +318,11 @@ <title>Encoding two pass MPEG-4 ("DivX")</title> <para> -The name comes from the fact that this method encodes the file <emphasis>twice</emphasis>. -The first encoding (dubbed pass) creates some temporary files -(<filename>*.log</filename>) with a size of few megabytes, do not delete -them yet (you can delete the AVI or rather just not create any video by -redirecting it into <filename>/dev/null</filename>). +The name comes from the fact that this method encodes the file +<emphasis>twice</emphasis>. The first encoding (dubbed pass) creates some +temporary files (<filename>*.log</filename>) with a size of few megabytes, do +not delete them yet (you can delete the AVI or rather just not create any video +by redirecting it into <filename>/dev/null</filename>). In the second pass, the two pass output file is created, using the bitrate data from the temporary files. The resulting file will have much better image quality. If this is the first @@ -556,16 +556,16 @@ <para> <application>MEncoder</application> is capable of creating movies from one -or more JPEG, PNG, TGA, or other image files. With simple framecopy it can create MJPEG -(Motion JPEG), MPNG (Motion PNG) or MTGA (Motion TGA) files. +or more JPEG, PNG, TGA, or other image files. With simple framecopy it can +create MJPEG (Motion JPEG), MPNG (Motion PNG) or MTGA (Motion TGA) files. </para> <orderedlist> <title>Explanation of the process:</title> <listitem><para> - <application>MEncoder</application> <emphasis>decodes</emphasis> the input image(s) with - <systemitem class="library">libjpeg</systemitem> (when decoding PNGs, it - will use <systemitem class="library">libpng</systemitem>). + <application>MEncoder</application> <emphasis>decodes</emphasis> the input + image(s) with <systemitem class="library">libjpeg</systemitem> (when decoding + PNGs, it will use <systemitem class="library">libpng</systemitem>). </para></listitem> <listitem><para> <application>MEncoder</application> then feeds the decoded image to the @@ -600,8 +600,8 @@ <informalexample> <para> -Creating an MPEG-4 file from explicit list of JPEG files (list.txt in current directory -contains the list of files to use as source, one per line): +Creating an MPEG-4 file from explicit list of JPEG files (list.txt in current +directory contains the list of files to use as source, one per line): <screen> mencoder mf://<replaceable>@list.txt</replaceable> -mf w=800:h=600:fps=25:type=jpg \ -ovc lavc -lavcopts vcodec=mpeg4:mbd=2:trell -oac copy -o <replaceable>output.avi</replaceable> @@ -629,7 +629,8 @@ </informalexample> <note><para> -Width must be integer multiple of 4, it is a limitation of the RAW RGB AVI format. +Width must be integer multiple of 4, it is a limitation of the RAW RGB AVI +format. </para></note> <informalexample> @@ -737,9 +738,9 @@ <para> MPEG-4 has a unique feature: the video stream can contain its needed aspect -ratio. Yes, just like MPEG-1/2 (DVD, SVCD) and H.263 files. Regretfully, there are -few video players apart from <application>MPlayer</application> that support this -MPEG-4 attribute. +ratio. Yes, just like MPEG-1/2 (DVD, SVCD) and H.263 files. Regretfully, there +are few video players apart from <application>MPlayer</application> that +support this MPEG-4 attribute. </para> <para>
--- a/DOCS/xml/en/ports.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/ports.xml Fri Dec 08 11:38:06 2006 +0000 @@ -5,16 +5,21 @@ <sect1 id="linux"> <title>Linux</title> + <para> The main development platform is Linux on x86, although <application>MPlayer</application> works on many other Linux ports. Binary packages of <application>MPlayer</application> are available from several -sources. However, <emphasis role="bold">none of these packages are supported</emphasis>. +sources. +However, <emphasis role="bold">none of these packages are supported</emphasis>. Report problems to the authors, not to us. </para> +<!-- ********** --> + <sect2 id="debian"> <title>Debian packaging</title> + <para> To build a Debian package, run the following command in the <application>MPlayer</application> source directory: @@ -49,16 +54,21 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="rpm"> <title>RPM packaging</title> + <para> Dominik Mierzejewski created and maintains the official RPM packages of -<application>MPlayer</application> for Red Hat and Fedora Core. They are available +<application>MPlayer</application> for Red Hat and Fedora Core. They are +available from his <ulink url="http://rpm.greysector.net/mplayer/">repository</ulink>. </para> <para> -Mandrake/Mandriva RPM packages are available from the <ulink url="http://plf.zarb.org/">P.L.F.</ulink>. +Mandrake/Mandriva RPM packages are available from the +<ulink url="http://plf.zarb.org/">P.L.F.</ulink>. SuSE used to include a crippled version of <application>MPlayer</application> in their distribution. They have removed it in their latest releases. You can get working RPMs from @@ -66,13 +76,17 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="arm"> <title>ARM</title> + <para> -<application>MPlayer</application> works on Linux PDAs with ARM CPU e.g. Sharp Zaurus, -Compaq Ipaq. The easiest way to obtain <application>MPlayer</application> is to get it -from one of the <ulink url="http://www.openzaurus.org">OpenZaurus</ulink> package feeds. If -you want to compile it yourself, you should look at the +<application>MPlayer</application> works on Linux PDAs with ARM CPU e.g. Sharp +Zaurus, Compaq Ipaq. The easiest way to obtain +<application>MPlayer</application> is to get it from one of the +<ulink url="http://www.openzaurus.org">OpenZaurus</ulink> package feeds. +If you want to compile it yourself, you should look at the <ulink url="http://openzaurus.bkbits.net:8080/buildroot/src/packages/mplayer?nav=index.html|src/.|src/packages">mplayer</ulink> and the <ulink url="http://openzaurus.bkbits.net:8080/buildroot/src/packages/libavcodec?nav=index.html|src/.|src/packages">libavcodec</ulink> @@ -83,8 +97,13 @@ </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bsd"> <title>*BSD</title> + <para> <application>MPlayer</application> runs on all known BSD flavors. There are ports/pkgsrc/fink/etc versions of <application>MPlayer</application> @@ -97,8 +116,9 @@ </para> <para> -If <application>MPlayer</application> complains about not finding <filename>/dev/cdrom</filename> -or <filename>/dev/dvd</filename>, create an appropriate symbolic link: +If <application>MPlayer</application> complains about not finding +<filename>/dev/cdrom</filename> or <filename>/dev/dvd</filename>, +create an appropriate symbolic link: <screen>ln -s /dev/<replaceable>your_cdrom_device</replaceable> /dev/cdrom</screen> </para> @@ -109,9 +129,11 @@ where this is the default). </para> +<!-- ********** --> <sect2 id="freebsd"> <title>FreeBSD</title> + <para> If your CPU has SSE, recompile your kernel with "<envar>options CPU_ENABLE_SSE</envar>" (FreeBSD-STABLE or kernel @@ -119,27 +141,38 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="openbsd"> <title>OpenBSD</title> + <para> Due to limitations in different versions of gas (relocation vs MMX), you will need to compile in two steps: First make sure that the non-native as is first in your <envar>$PATH</envar> and do a <command>gmake -k</command>, then make sure that the native version is used and do <command>gmake</command>. </para> + <para> As of OpenBSD 3.4 the hack above is no longer needed. </para> </sect2> +<!-- ********** --> + <sect2 id="darwin"> <title>Darwin</title> + <para> See the <link linkend="macos">Mac OS</link> section. </para> </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="unix"> <title>Commercial Unix</title> @@ -150,16 +183,20 @@ adjustments to make the build work. </para> +<!-- ********** --> + <sect2 id="solaris"> <title>Solaris</title> + <para> <application>MPlayer</application> should work on Solaris 2.6 or newer. Use the SUN audio driver with the <option>-ao sun</option> option for sound. </para> <para> -On <emphasis role="bold">UltraSPARCs</emphasis>, <application>MPlayer</application> -takes advantage of their <emphasis role="bold">VIS</emphasis> extensions +On <emphasis role="bold">UltraSPARCs</emphasis>, +<application>MPlayer</application> takes advantage of their +<emphasis role="bold">VIS</emphasis> extensions (equivalent to MMX), currently only in <systemitem class="library">libmpeg2</systemitem>, <systemitem class="library">libvo</systemitem> @@ -172,18 +209,17 @@ <para><emphasis role="bold">Caveat:</emphasis></para> <itemizedlist> -<listitem><para><emphasis role="bold">mediaLib</emphasis> is -<emphasis role="bold">currently disabled</emphasis> by default in -<application>MPlayer</application> because of brokenness. SPARC users -who build MPlayer with mediaLib support have reported a thick, -green-tint on video encoded and decoded with libavcodec. You may enable -it if you wish with: -<screen> -$ ./configure --enable-mlib -</screen> -You do this at your own risk. x86 users should -<emphasis role="bold">never</emphasis> use mediaLib, as this will -result in very poor MPlayer performance. +<listitem><para> + <emphasis role="bold">mediaLib</emphasis> is + <emphasis role="bold">currently disabled</emphasis> by default in + <application>MPlayer</application> because of brokenness. SPARC users + who build MPlayer with mediaLib support have reported a thick, + green-tint on video encoded and decoded with libavcodec. You may enable + it if you wish with: + <screen>./configure --enable-mlib</screen> + You do this at your own risk. x86 users should + <emphasis role="bold">never</emphasis> use mediaLib, as this will + result in very poor MPlayer performance. </para></listitem> </itemizedlist> @@ -193,8 +229,8 @@ Solaris make will not work. Typical error you get when building with Solaris' make instead of GNU make: <screen> - % /usr/ccs/bin/make - make: Fatal error in reader: Makefile, line 25: Unexpected end of line seen +% /usr/ccs/bin/make +make: Fatal error in reader: Makefile, line 25: Unexpected end of line seen </screen> </para> @@ -207,13 +243,15 @@ On Solaris x86, you need the GNU assembler and the GNU C/C++ compiler, configured to use the GNU assembler! The <application>MPlayer</application> code on the x86 platform makes heavy use of MMX, SSE and 3DNOW! instructions -that cannot be compiled using Sun's assembler <filename>/usr/ccs/bin/as</filename>. +that cannot be compiled using Sun's assembler +<filename>/usr/ccs/bin/as</filename>. </para> <para> -The <filename>configure</filename> script tries to find out, which -assembler program is used by your "gcc" command (in case the autodetection -fails, use the <option>--as=<replaceable>/wherever/you/have/installed/gnu-as</replaceable></option> +The <filename>configure</filename> script tries to find out, which assembler +program is used by your "gcc" command (in case the autodetection +fails, use the +<option>--as=<replaceable>/wherever/you/have/installed/gnu-as</replaceable></option> option to tell the <filename>configure</filename> script where it can find GNU "as" on your system). </para> @@ -221,35 +259,38 @@ <para>Solutions to common problems:</para> <itemizedlist> <listitem><para> -Error message from <filename>configure</filename> on a Solaris x86 system using -GCC without GNU assembler: -<screen> - % configure - ... - Checking assembler (/usr/ccs/bin/as) ... , failed - Please upgrade(downgrade) binutils to 2.10.1... -</screen> -(Solution: Install and use a gcc configured with <option>--with-as=gas</option>) + Error message from <filename>configure</filename> on a Solaris x86 system + using GCC without GNU assembler: + <screen> +% configure +... +Checking assembler (/usr/ccs/bin/as) ... , failed +Please upgrade(downgrade) binutils to 2.10.1...<!-- + --></screen> + (Solution: Install and use a gcc configured with + <option>--with-as=gas</option>) </para> <para> -Typical error you get when building with a GNU C compiler that does not use GNU as: +Typical error you get when building with a GNU C compiler that does not +use GNU as: <screen> - % gmake - ... - gcc -c -Iloader -Ilibvo -O4 -march=i686 -mcpu=i686 -pipe -ffast-math - -fomit-frame-pointer -I/usr/local/include -o mplayer.o mplayer.c - Assembler: mplayer.c - "(stdin)", line 3567 : Illegal mnemonic - "(stdin)", line 3567 : Syntax error - ... more "Illegal mnemonic" and "Syntax error" errors ... +% gmake +... +gcc -c -Iloader -Ilibvo -O4 -march=i686 -mcpu=i686 -pipe -ffast-math + -fomit-frame-pointer -I/usr/local/include -o mplayer.o mplayer.c +Assembler: mplayer.c +"(stdin)", line 3567 : Illegal mnemonic +"(stdin)", line 3567 : Syntax error +... more "Illegal mnemonic" and "Syntax error" errors ... </screen> </para> </listitem> -<listitem><para><application>MPlayer</application> may segfault when decoding -and encoding video that uses the win32codecs: -<screen> +<listitem><para> + <application>MPlayer</application> may segfault when decoding + and encoding video that uses the win32codecs: + <screen> ... Trying to force audio codec driver family acm... Opening audio decoder: [acm] Win32/ACM decoders @@ -258,50 +299,56 @@ MPlayer interrupted by signal 11 in module: init_audio_codec -... -</screen> -This is because of a change to sysi86() in Solaris 10 and pre-Solaris -Nevada b31 releases. This has been fixed in Solaris Nevada b32; -however, Sun has yet to backport the fix to Solaris 10. The MPlayer -Project has made Sun aware of the problem and a patch is currently in -progress for Solaris 10. More information about this bug can be found -at: -<ulink -url="http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=6308413"/>. -</para> -</listitem> +...<!-- + --></screen> + This is because of a change to sysi86() in Solaris 10 and pre-Solaris + Nevada b31 releases. This has been fixed in Solaris Nevada b32; + however, Sun has yet to backport the fix to Solaris 10. The MPlayer + Project has made Sun aware of the problem and a patch is currently in + progress for Solaris 10. More information about this bug can be found + at: + <ulink url="http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=6308413"/>. +</para></listitem> <listitem><para> -Due to bugs in Solaris 8, you may not be able to play DVD discs larger than 4 GB: +Due to bugs in Solaris 8, +you may not be able to play DVD discs larger than 4 GB: </para> <itemizedlist> <listitem><para> -The sd(7D) driver on Solaris 8 x86 has a bug when accessing a disk block >4GB -on a device using a logical blocksize != DEV_BSIZE (i.e. CD-ROM and DVD media). -Due to a 32Bit int overflow, a disk address modulo 4GB is accessed -(<ulink url="http://groups.yahoo.com/group/solarisonintel/message/22516"/>). -This problem does not exist in the SPARC version of Solaris 8. + The sd(7D) driver on Solaris 8 x86 has a bug when accessing a disk block >4GB + on a device using a logical blocksize != DEV_BSIZE + (i.e. CD-ROM and DVD media). + Due to a 32Bit int overflow, a disk address modulo 4GB is accessed + (<ulink url="http://groups.yahoo.com/group/solarisonintel/message/22516"/>). + This problem does not exist in the SPARC version of Solaris 8. </para></listitem> <listitem><para> -A similar bug is present in the hsfs(7FS) filesystem code (AKA ISO9660), -hsfs may not not support partitions/disks larger than 4GB, all data is -accessed modulo 4GB -(<ulink url="http://groups.yahoo.com/group/solarisonintel/message/22592"/>). -The hsfs problem can be fixed by installing patch 109764-04 (sparc) / 109765-04 (x86). + A similar bug is present in the hsfs(7FS) filesystem code (AKA ISO9660), + hsfs may not not support partitions/disks larger than 4GB, all data is + accessed modulo 4GB + (<ulink url="http://groups.yahoo.com/group/solarisonintel/message/22592"/>). + The hsfs problem can be fixed by installing + patch 109764-04 (sparc) / 109765-04 (x86). </para></listitem> </itemizedlist> </listitem> </itemizedlist> </sect2> +<!-- ********** --> + <sect2 id="irix"> <title>IRIX</title> + <para> You can either try to install the GNU install program, and (if you did not put it in your global path) then point to the location with: -<screen>./configure --with-install=<replaceable>/path/and/name/of/install</replaceable></screen> +<screen> +./configure --with-install=<replaceable>/path/and/name/of/install</replaceable> +</screen> </para> <para> @@ -309,15 +356,15 @@ you will have to edit the <filename>Makefile</filename> by hand a little bit. Change the following two lines: <programlisting> - $(INSTALL) -c -m 644 DOCS/mplayer.1 $(MANDIR)/man1/mplayer.1 +$(INSTALL) -c -m 644 DOCS/mplayer.1 $(MANDIR)/man1/mplayer.1 - $(INSTALL) -c -m 644 etc/codecs.conf $(CONFDIR)/codecs.conf +$(INSTALL) -c -m 644 etc/codecs.conf $(CONFDIR)/codecs.conf </programlisting> to: <programlisting> - $(INSTALL) -m 644 mplayer.1 $(MANDIR)/man1/ +$(INSTALL) -m 644 mplayer.1 $(MANDIR)/man1/ - $(INSTALL) -m 644 codecs.conf $(CONFDIR)/ +$(INSTALL) -m 644 codecs.conf $(CONFDIR)/ </programlisting> And then do (from within the <application>MPlayer</application> source dir): <screen>cp DOCS/mplayer.1 . ; cp etc/codecs.conf .</screen> @@ -325,9 +372,11 @@ </para> </sect2> +<!-- ********** --> <sect2 id="hp-ux"> <title>HP-UX</title> + <para> Joe Page hosts a detailed HP-UX <application>MPlayer</application> <ulink url="http://users.rcn.com/joepage/mplayer_on_hpux11.htm">HOWTO</ulink> @@ -347,7 +396,6 @@ <para> Create the DVD device scan the SCSI bus with: -</para> <screen> # ioscan -fn @@ -364,89 +412,81 @@ ... </screen> -<para> The screen output shows a Pioneer DVD-ROM at SCSI address 2. The card instance for hardware path 8/16 is 1. </para> <para> Create a link from the raw device to the DVD device. -</para> - <screen> -# ln -s /dev/rdsk/c<replaceable><SCSI bus instance></replaceable>t<replaceable><SCSI target ID></replaceable>d<replaceable><LUN></replaceable> /dev/<replaceable><device></replaceable> +ln -s /dev/rdsk/c<replaceable><SCSI bus instance></replaceable>t<replaceable><SCSI target ID></replaceable>d<replaceable><LUN></replaceable> /dev/<replaceable><device></replaceable> </screen> - -<para> Example: +<screen>ln -s /dev/rdsk/c1t2d0 /dev/dvd</screen> </para> -<screen> -# ln -s /dev/rdsk/c1t2d0 /dev/dvd -</screen> - <para> Below are solutions for some common problems: -</para> <itemizedlist> <listitem> -<para> -Crash at Start with the following error message: -<screen> -/usr/lib/dld.sl: Unresolved symbol: finite (code) from /usr/local/lib/gcc-lib/hppa2.0n-hp-hpux11.00/3.2/../../../libGL.sl -</screen> -</para> - -<para> -This means that the function <systemitem>.finite().</systemitem> is not -available in the standard HP-UX math library. -Instead there is <systemitem>.isfinite().</systemitem>. -Solution: Use the latest Mesa depot file. -</para> + <para> + Crash at Start with the following error message: + <screen> +/usr/lib/dld.sl: Unresolved symbol: finite (code) from /usr/local/lib/gcc-lib/hppa2.0n-hp-hpux11.00/3.2/../../../libGL.sl<!-- + --></screen> + </para> + <para> + This means that the function <systemitem>.finite().</systemitem> is not + available in the standard HP-UX math library. + Instead there is <systemitem>.isfinite().</systemitem>. + Solution: Use the latest Mesa depot file. + </para> </listitem> <listitem> -<para> -Crash at playback with the following error message: -<screen> -/usr/lib/dld.sl: Unresolved symbol: sem_init (code) from /usr/local/lib/libSDL-1.2.sl.0 -</screen> -</para> - -<para> -Solution: Use the extralibdir option of configure -<option>--with-extralibdir="/usr/lib -lrt"</option> -</para> + <para> + Crash at playback with the following error message: + <screen> +/usr/lib/dld.sl: Unresolved symbol: sem_init (code) from /usr/local/lib/libSDL-1.2.sl.0<!-- + --></screen> + </para> + <para> + Solution: Use the extralibdir option of configure + <option>--with-extralibdir="/usr/lib -lrt"</option> + </para> </listitem> <listitem> -<para> -MPlayer segfaults with a message like this: -<screen> + <para> + MPlayer segfaults with a message like this: + <screen> Pid 10166 received a SIGSEGV for stack growth failure. Possible causes: insufficient memory or swap space, or stack size exceeded maxssiz. -Segmentation fault -</screen> -</para> - -<para> -Solution: -The HP-UX kernel has a default stack size of 8MB(?) per process.(11.0 and -newer 10.20 patches let you increase <systemitem>maxssiz</systemitem> up to -350MB for 32-bit programs). You need to extend <systemitem>maxssiz</systemitem> -and recompile the kernel (and reboot). You can use SAM to do this. (While at -it, check out the <systemitem>maxdsiz</systemitem> parameter for the maximum -amount of data a program can use. It depends on your applications, if the -default of 64MB is enough or not.) -</para> +Segmentation fault<!-- + --></screen> + </para> + <para> + Solution: + The HP-UX kernel has a default stack size of 8MB(?) per process.(11.0 and + newer 10.20 patches let you increase <systemitem>maxssiz</systemitem> up to + 350MB for 32-bit programs). You need to extend + <systemitem>maxssiz</systemitem> and recompile the kernel (and reboot). + You can use SAM to do this. + (While at it, check out the <systemitem>maxdsiz</systemitem> parameter for + the maximum amount of data a program can use. + It depends on your applications, if the default of 64MB is enough or not.) + </para> </listitem> </itemizedlist> +</para> +</sect2> -</sect2> +<!-- ********** --> <sect2 id="aix"> <title>AIX</title> + <para> <application>MPlayer</application> builds successfully on AIX 5.1, 5.2, and 5.3, using GCC 3.3 or greater. Building @@ -469,26 +509,25 @@ </para> <itemizedlist> -<listitem><para>604e</para></listitem> -<listitem><para>POWER3</para></listitem> -<listitem><para>POWER4</para></listitem> + <listitem><para>604e</para></listitem> + <listitem><para>POWER3</para></listitem> + <listitem><para>POWER4</para></listitem> </itemizedlist> <para> The following architectures are untested, but should still work: +<itemizedlist> + <listitem><para>POWER</para></listitem> + <listitem><para>POWER2</para></listitem> + <listitem><para>POWER5</para></listitem> +</itemizedlist> </para> -<itemizedlist> -<listitem><para>POWER</para></listitem> -<listitem><para>POWER2</para></listitem> -<listitem><para>POWER5</para></listitem> -</itemizedlist> <para> Sound via the Ultimedia Services is not supported, as Ultimedia was dropped in AIX 5.1; therefore, the only option is to use the AIX Open -Sound System (OSS) drivers from 4Front Technologies at <ulink -url="http://www.opensound.com/aix.html">http://www.opensound.com/aix.html -</ulink>. +Sound System (OSS) drivers from 4Front Technologies at +<ulink url="http://www.opensound.com/aix.html">http://www.opensound.com/aix.html</ulink>. 4Front Technologies freely provides OSS drivers for AIX 5.1 for non-commercial use; however, there are currently no sound output drivers for AIX 5.2 or 5.3. This means <emphasis role="bold">AIX 5.2 @@ -500,99 +539,103 @@ <itemizedlist> <listitem> <para> -If you encounter this error message from <filename>configure</filename>: -<screen> + If you encounter this error message from <filename>./configure</filename>: + <screen> $ ./configure ... Checking for iconv program ... no No working iconv program found, use --charset=US-ASCII to continue anyway. -Messages in the GTK-2 interface will be broken then. -</screen> -This is because AIX uses non-standard character set names; therefore, -converting MPlayer output to another character set is currently not -supported. The solution is to use: -<screen> -$ ./configure --charset=noconv -</screen> -</para> +Messages in the GTK-2 interface will be broken then.<!-- + --></screen> + This is because AIX uses non-standard character set names; therefore, + converting MPlayer output to another character set is currently not + supported. The solution is to use: + <screen>$ ./configure --charset=noconv</screen> + </para> </listitem> </itemizedlist> - </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="windows"> <title>Windows</title> -<para>Yes, <application>MPlayer</application> runs on Windows under - <ulink url="http://www.cygwin.com/"><application>Cygwin</application></ulink> and - <ulink url="http://www.mingw.org/"><application>MinGW</application></ulink>. - It does not have an official GUI yet, but the command line version - is completely functional. You should check out the - <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-cygwin/">MPlayer-cygwin</ulink> - mailing list for help and latest information. - Official Windows binaries can be found on the - <ulink url="http://www.mplayerhq.hu/design7/dload.html">download page</ulink>. - Installer packages and simple GUI frontends are available from external - sources, we have collected then in the Windows section of our - <ulink url="http://www.mplayerhq.hu/design7/projects.html#windows">projects page</ulink>. +<para> +Yes, <application>MPlayer</application> runs on Windows under +<ulink url="http://www.cygwin.com/"><application>Cygwin</application></ulink> +and +<ulink url="http://www.mingw.org/"><application>MinGW</application></ulink>. +It does not have an official GUI yet, but the command line version +is completely functional. You should check out the +<ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-cygwin/">MPlayer-cygwin</ulink> +mailing list for help and latest information. +Official Windows binaries can be found on the +<ulink url="http://www.mplayerhq.hu/design7/dload.html">download page</ulink>. +Installer packages and simple GUI frontends are available from external +sources, we have collected then in the Windows section of our +<ulink url="http://www.mplayerhq.hu/design7/projects.html#windows">projects page</ulink>. </para> -<para>If you wish to avoid using the command line, a simple trick is - to put a shortcut on your desktop that contains something like the - following in the execute section: - <screen><replaceable>c:\path\to\</replaceable>mplayer.exe %1</screen> - This will make <application>MPlayer</application> play any movie that is - dropped on the shortcut. Add <option>-fs</option> for fullscreen mode. +<para> +If you wish to avoid using the command line, a simple trick is +to put a shortcut on your desktop that contains something like the +following in the execute section: +<screen><replaceable>c:\path\to\</replaceable>mplayer.exe %1</screen> +This will make <application>MPlayer</application> play any movie that is +dropped on the shortcut. Add <option>-fs</option> for fullscreen mode. </para> -<para>Best results are achieved with the native DirectX video output driver - (<option>-vo directx</option>). Alternatives are OpenGL and SDL, but OpenGL - performance varies greatly between systems and SDL is known to - distort video or crash on some systems. If the image is - distorted, try turning off hardware acceleration with - <option>-vo directx:noaccel</option>. Download - <ulink url="http://www.mplayerhq.hu/MPlayer/releases/win32/contrib/dx7headers.tgz">DirectX 7 header files</ulink> - to compile the DirectX video output driver. Furthermore you need to have - DirectX 7 or later installed for the DirectX video output driver to work. - </para> - -<para><link linkend="vidix">VIDIX</link> now works under Windows as - <option>-vo winvidix</option>, although it is still experimental - and needs a bit of manual setup. Download - <ulink url="http://www.mplayerhq.hu/MPlayer/releases/win32/dhahelperwin/dhahelper.sys">dhahelper.sys</ulink> or - <ulink url="http://www.mplayerhq.hu/MPlayer/releases/win32/dhahelperwin/withmtrr/dhahelper.sys">dhahelper.sys (with MTRR support)</ulink> - and copy it to the - <filename class="directory">libdha/dhahelperwin</filename> directory in your - <application>MPlayer</application> source tree. - Open a console and change to that directory. Then type - - <screen>gcc -o dhasetup.exe dhasetup.c</screen> +<para> +Best results are achieved with the native DirectX video output driver +(<option>-vo directx</option>). Alternatives are OpenGL and SDL, but OpenGL +performance varies greatly between systems and SDL is known to +distort video or crash on some systems. If the image is +distorted, try turning off hardware acceleration with +<option>-vo directx:noaccel</option>. Download +<ulink url="http://www.mplayerhq.hu/MPlayer/releases/win32/contrib/dx7headers.tgz">DirectX 7 header files</ulink> +to compile the DirectX video output driver. Furthermore you need to have +DirectX 7 or later installed for the DirectX video output driver to work. +</para> - and execute - - <screen>dhasetup.exe install</screen> - - as Administrator. After that you will have to reboot. When you are - done, copy the <systemitem class="library">.so</systemitem> files from - <filename class="directory">vidix/drivers</filename> to the - <filename class="directory">mplayer/vidix</filename> directory - relative to your <filename>mplayer.exe</filename>.</para> +<para> +<link linkend="vidix">VIDIX</link> now works under Windows as +<option>-vo winvidix</option>, although it is still experimental +and needs a bit of manual setup. Download +<ulink url="http://www.mplayerhq.hu/MPlayer/releases/win32/dhahelperwin/dhahelper.sys">dhahelper.sys</ulink> or +<ulink url="http://www.mplayerhq.hu/MPlayer/releases/win32/dhahelperwin/withmtrr/dhahelper.sys">dhahelper.sys (with MTRR support)</ulink> +and copy it to the <filename class="directory">libdha/dhahelperwin</filename> +directory in your <application>MPlayer</application> source tree. +Open a console and change to that directory. Then type +<screen>gcc -o dhasetup.exe dhasetup.c</screen> +and execute +<screen>dhasetup.exe install</screen> +as Administrator. After that you will have to reboot. When you are +done, copy the <systemitem class="library">.so</systemitem> files from +<filename class="directory">vidix/drivers</filename> to the +<filename class="directory">mplayer/vidix</filename> directory +relative to your <filename>mplayer.exe</filename>. +</para> -<para>For best results <application>MPlayer</application> should use a - colorspace that your video card supports in hardware. Unfortunately many - Windows graphics drivers wrongly report some colorspaces as supported in - hardware. To find out which, try - - <screen>mplayer -benchmark -nosound -frames 100 -vf format=<replaceable>colorspace</replaceable> <replaceable>movie</replaceable></screen> - - where <replaceable>colorspace</replaceable> can be any colorspace - printed by the <option>-vf format=fmt=help</option> option. If you - find a colorspace your card handles particularly bad - <option>-vf noformat=<replaceable>colorspace</replaceable></option> - will keep it from being used. Add this to your config file to permanently - keep it from being used.</para> +<para> +For best results <application>MPlayer</application> should use a +colorspace that your video card supports in hardware. Unfortunately many +Windows graphics drivers wrongly report some colorspaces as supported in +hardware. To find out which, try +<screen> +mplayer -benchmark -nosound -frames 100 -vf format=<replaceable>colorspace</replaceable> <replaceable>movie</replaceable> +</screen> +where <replaceable>colorspace</replaceable> can be any colorspace +printed by the <option>-vf format=fmt=help</option> option. If you +find a colorspace your card handles particularly bad +<option>-vf noformat=<replaceable>colorspace</replaceable></option> +will keep it from being used. Add this to your config file to permanently +keep it from being used. +</para> <para>There are special codec packages for Windows available on our <ulink url="http://www.mplayerhq.hu/design7/dload.html">download page</ulink> @@ -604,83 +647,102 @@ only on <application>Cygwin</application>) to <filename>configure</filename>. We have had some reports that Real DLLs need to be writable by the user running <application>MPlayer</application>, but only on some systems (NT4). - Try making them writable if you have problems.</para> - -<para>You can play VCDs by playing the <filename>.DAT</filename> or <filename>.MPG</filename> files - that Windows exposes on VCDs. It works like this (adjust for the drive letter - of your CD-ROM):</para> - -<screen>mplayer <replaceable>d:/mpegav/avseq01.dat</replaceable></screen> + Try making them writable if you have problems. + </para> -<para>DVDs also work, adjust <option>-dvd-device</option> for the drive letter - of your DVD-ROM:</para> - -<screen>mplayer dvd://<replaceable><title></replaceable> -dvd-device <replaceable>d</replaceable>:</screen> - -<para>The <application>Cygwin</application>/<application>MinGW</application> - console is rather slow. Redirecting output or using the - <option>-quiet</option> option has been reported to improve performance on - some systems. Direct rendering (<option>-dr</option>) may also help. - If playback is jerky, try - <option>-autosync 100</option>. If some of these options help you, you - may want to put them in your config file.</para> +<para> +You can play VCDs by playing the <filename>.DAT</filename> or +<filename>.MPG</filename> files that Windows exposes on VCDs. It works like +this (adjust for the drive letter of your CD-ROM): +<screen>mplayer <replaceable>d:/mpegav/avseq01.dat</replaceable></screen> +DVDs also work, adjust <option>-dvd-device</option> for the drive letter +of your DVD-ROM: +<screen> +mplayer dvd://<replaceable><title></replaceable> -dvd-device <replaceable>d</replaceable>: +</screen> +The <application>Cygwin</application>/<application>MinGW</application> +console is rather slow. Redirecting output or using the +<option>-quiet</option> option has been reported to improve performance on +some systems. Direct rendering (<option>-dr</option>) may also help. +If playback is jerky, try +<option>-autosync 100</option>. If some of these options help you, you +may want to put them in your config file. +</para> <note> - -<para>On Windows the runtime CPU detection disables SSE support - because of recurring and hard-to-trace SSE-related crashes. If you - wish to have SSE support under Windows, you will have to compile without - runtime CPU-detection. +<para> +On Windows the runtime CPU detection disables SSE support +because of recurring and hard-to-trace SSE-related crashes. If you +wish to have SSE support under Windows, you will have to compile without +runtime CPU-detection. </para> -<para>If you have a Pentium 4 and are experiencing a crash using the - RealPlayer codecs, you may need to disable hyperthreading support. +<para> +If you have a Pentium 4 and are experiencing a crash using the +RealPlayer codecs, you may need to disable hyperthreading support. </para> - </note> +<!-- ********** --> <sect2 id="cygwin"> <title><application>Cygwin</application></title> -<para>You need to run <application>Cygwin</application> 1.5.0 or later in - order to compile <application>MPlayer</application>.</para> +<para> +You need to run <application>Cygwin</application> 1.5.0 or later in +order to compile <application>MPlayer</application>. +</para> -<para>DirectX header files need to be extracted to <filename class="directory">/usr/include/</filename> or - <filename class="directory">/usr/local/include/</filename>.</para> +<para> +DirectX header files need to be extracted to +<filename class="directory">/usr/include/</filename> or +<filename class="directory">/usr/local/include/</filename>. +</para> -<para>Instructions and files for making SDL run under - <application>Cygwin</application> can be found on the - <ulink url="http://www.libsdl.org/extras/win32/cygwin/">libsdl site</ulink>.</para> - +<para> +Instructions and files for making SDL run under +<application>Cygwin</application> can be found on the +<ulink url="http://www.libsdl.org/extras/win32/cygwin/">libsdl site</ulink>. +</para> </sect2> +<!-- ********** --> <sect2 id="mingw"> <title><application>MinGW</application></title> -<para>Installing a version of <application>MinGW</application> that could - compile <application>MPlayer</application> used to be quite tricky, but it - works out of the box now. Just install <application>MinGW</application> - 3.1.0 or later and MSYS 1.0.9 or later and tell the MSYS postinstall that - <application>MinGW</application> is installed.</para> +<para> +Installing a version of <application>MinGW</application> that could +compile <application>MPlayer</application> used to be quite tricky, but it +works out of the box now. Just install <application>MinGW</application> +3.1.0 or later and MSYS 1.0.9 or later and tell the MSYS postinstall that +<application>MinGW</application> is installed. +</para> -<para>Extract DirectX header files to <filename class="directory">/mingw/include/</filename>.</para> +<para> +Extract DirectX header files to +<filename class="directory">/mingw/include/</filename>. +</para> -<para>MOV compressed header support requires - <ulink url="http://www.gzip.org/zlib/">zlib</ulink>, which - <application>MinGW</application> does not provide by default. - Configure it with <option>--prefix=/mingw</option> and install - it before compiling <application>MPlayer</application>.</para> +<para> +MOV compressed header support requires +<ulink url="http://www.gzip.org/zlib/">zlib</ulink>, +which <application>MinGW</application> does not provide by default. +Configure it with <option>--prefix=/mingw</option> and install +it before compiling <application>MPlayer</application>. +</para> -<para>Complete instructions for building <application>MPlayer</application> - and necessary libraries can be found in the - <ulink url="http://mplayerhq.hu/MPlayer/releases/win32/contrib/MPlayer-MinGW-Howto.txt">MPlayer MinGW HOWTO</ulink>.</para> - +<para> +Complete instructions for building <application>MPlayer</application> +and necessary libraries can be found in the +<ulink url="http://mplayerhq.hu/MPlayer/releases/win32/contrib/MPlayer-MinGW-Howto.txt">MPlayer MinGW HOWTO</ulink>. +</para> </sect2> +</sect1> -</sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="macos"> <title>Mac OS</title> @@ -736,11 +798,16 @@ <systemitem>PKG_CONFIG_PATH</systemitem> and <systemitem>PATH</systemitem> environment variables so that <systemitem>configure</systemitem> finds the libraries installed with MacPorts): -<screen>PKG_CONFIG_PATH=/opt/local/lib/pkgconfig/ PATH=$PATH:/opt/local/bin/ ./configure</screen> +<screen> +PKG_CONFIG_PATH=/opt/local/lib/pkgconfig/ PATH=$PATH:/opt/local/bin/ ./configure +</screen> </para> +<!-- ********** --> + <sect2 id="osx_gui"> <title>MPlayer OS X GUI</title> + <para> You can get a native GUI for <application>MPlayer</application> together with precompiled <application>MPlayer</application> binaries for Mac OS X from the @@ -770,7 +837,6 @@ <para> To check out SVN modules use: - <screen> svn checkout svn://svn.mplayerhq.hu/mplayerosx/trunk/ mplayerosx svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ main @@ -780,7 +846,6 @@ <para> In order to build <application>MPlayerOSX</application> you will need to set up something like this: - <screen> MPlayer_source_directory | @@ -788,15 +853,13 @@ | |--->main_noaltivec (MPlayer Subversion source configured with --disable-altivec) | - |--->mplayerosx (MPlayer OS X Subversion source) + \--->mplayerosx (MPlayer OS X Subversion source) </screen> - You first need to build main and main_noaltivec. </para> <para> Next, set a global variable: - <screen>export MACOSX_DEPLOYMENT_TARGET=10.3</screen> </para> @@ -811,8 +874,8 @@ </screen> If you configure for a G3-powered machine without AltiVec, use: <screen> -./configure --with-termcaplib=ncurses.5 --disable-gl --disable-x11 ---disable-altivec +./configure --with-termcaplib=ncurses.5 --disable-gl --disable-x11 \ + --disable-altivec </screen> You may need to edit <filename>config.mak</filename> and change <systemitem>-mcpu</systemitem> and <systemitem>-mtune</systemitem> @@ -821,14 +884,9 @@ <para> Continue with -<screen> -make -</screen> +<screen>make</screen> then go to the mplayerosx directory and type - -<screen> -make dist -</screen> +<screen>make dist</screen> This will create a compressed <systemitem>.dmg</systemitem> archive with the ready to use binary. </para> @@ -841,6 +899,10 @@ </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="exotic_platforms"> <title>Exotic Platforms</title> @@ -851,8 +913,11 @@ For build instructions you should refer to the system-specific documentation. </para> +<!-- ********** --> + <sect2 id="qnx"> <title>QNX</title> + <para> You'll need to download and install SDL for QNX. Then run <application>MPlayer</application> with <option>-vo sdl:driver=photon</option> @@ -865,10 +930,13 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="amiga"> <title>Amiga/MorphOS (GeekGadgets)</title> <para> -The people over at <ulink url="http://www.amigasoft.net">www.amigasoft.net</ulink> +The people over at +<ulink url="http://www.amigasoft.net">www.amigasoft.net</ulink> make current <application>MPlayer</application> and <application>MEncoder</application> packages. </para> @@ -882,16 +950,16 @@ Get if from <ulink url="http://www.morphzone.org/">MorphZone</ulink>: <itemizedlist> <listitem><para> -<ulink url="http://www.morphzone.org/modules/mydownloads/singlefile.php?lid=90"> -<application>MPlayer</application> 0.91 binary</ulink> + <ulink url="http://www.morphzone.org/modules/mydownloads/singlefile.php?lid=90"> + <application>MPlayer</application> 0.91 binary</ulink> </para></listitem> <listitem><para> -<ulink url="http://www.morphzone.org/modules/mydownloads/singlefile.php?lid=91"> -<application>MPlayer</application> 0.91 source</ulink> + <ulink url="http://www.morphzone.org/modules/mydownloads/singlefile.php?lid=91"> + <application>MPlayer</application> 0.91 source</ulink> </para></listitem> <listitem><para> -<ulink url="http://www.morphzone.org/modules/mydownloads/singlefile.php?lid=92"> -<application>MEncoder</application> 1.0pre3 binary</ulink> + <ulink url="http://www.morphzone.org/modules/mydownloads/singlefile.php?lid=92"> + <application>MEncoder</application> 1.0pre3 binary</ulink> </para></listitem> </itemizedlist> </para>
--- a/DOCS/xml/en/radio.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/radio.xml Fri Dec 08 11:38:06 2006 +0000 @@ -12,96 +12,80 @@ description of radio options and keyboard controls. </para> +<!-- ********** --> <sect2 id="radio-compilation"> <title>Compilation</title> <procedure> <step><para> - First, you have to recompile MPlayer using <filename>./configure</filename> with - <option>--enable-radio</option> and (if you want capture support) + First, you have to recompile MPlayer using <filename>./configure</filename> + with <option>--enable-radio</option> and (if you want capture support) <option>--enable-radio-capture</option>. - </para></step> +</para></step> <step><para> Make sure your tuner works with another radio software in Linux, for example <application>XawTV</application>. - </para></step> +</para></step> </procedure> </sect2> +<!-- ********** --> + <sect2 id="radio-tips"> <title>Usage tips</title> + <para> The full listing of the options is available in the manual page. Here are just a few tips: -</para> <itemizedlist> -<listitem> -<para> -Use the <option>channels</option> option. An example: -<screen>-radio channels=104.4-Sibir,103.9-Maximum</screen> -Explanation: With this option, only the 104.4 and 103.9 radio stations -will be usable. There will be a nice OSD text upon channel switching, -displaying the channel's name. Spaces in the channel name must be -replaced by the "_" character. +<listitem><para> + Use the <option>channels</option> option. An example: + <screen>-radio channels=104.4-Sibir,103.9-Maximum</screen> + Explanation: With this option, only the 104.4 and 103.9 radio stations + will be usable. There will be a nice OSD text upon channel switching, + displaying the channel's name. Spaces in the channel name must be + replaced by the "_" character. +</para></listitem> +<listitem><para> + There are several ways of capturing audio. You can grab the sound either using + your sound card via an external cable connection between video card and + line-in, or using the built-in ADC in the saa7134 chip. In the latter case, + you have to load the <systemitem>saa7134-alsa</systemitem> or +<systemitem>saa7134-oss</systemitem> driver. +</para></listitem> +<listitem><para> + <application>MEncoder</application> cannot be used for audio capture, + because it requires a video stream to work. So your can either use + <application>arecord</application> from ALSA project or + use <option>-ao pcm:file=file.wav</option>. In the latter case you + will not hear any sound (unless you are using a line-in cable and + have switched line-in mute off). +</para></listitem> +</itemizedlist> </para> -</listitem> - -<listitem> -<para> -There are several ways of capturing audio. You can grab the sound either using -your sound card via an external cable connection between video card and line-in, -or using the built-in ADC in the saa7134 chip. In the latter case, you have to -load the <systemitem>saa7134-alsa</systemitem> or -<systemitem>saa7134-oss</systemitem> driver. -</para> -</listitem> - -<listitem> -<para> -<application>MEncoder</application> cannot be used for audio capture, because it -requires a video stream to work. So your can either use -<application>arecord</application> from ALSA project or -use <option>-ao pcm:file=file.wav</option>. In the latter case you -will not hear any sound (unless you are using a line-in cable and -have switched line-in mute off). -</para> -</listitem> -</itemizedlist> </sect2> +<!-- ********** --> <sect2 id="radio-examples"> <title>Examples</title> - -<informalexample> -<para> +<informalexample><para> Input from standard V4L (using line-in cable, capture switched off): -<screen> -mplayer radio://104.4 -</screen> -</para> -</informalexample> +<screen>mplayer radio://104.4</screen> +</para></informalexample> -<informalexample> -<para> +<informalexample><para> Input from standard V4L (using line-in cable, capture switched off, V4Lv1 interface): -<screen> -mplayer -radio driver=v4l radio://104.4 -</screen> -</para> -</informalexample> +<screen>mplayer -radio driver=v4l radio://104.4</screen> +</para></informalexample> -<informalexample> -<para> +<informalexample><para> Playing second channel from channel list: -<screen> -mplayer -radio channels=104.4=Sibir,103.9=Maximm radio://2 -</screen> -</para> -</informalexample> +<screen>mplayer -radio channels=104.4=Sibir,103.9=Maximm radio://2</screen> +</para></informalexample> <informalexample> <para> @@ -110,7 +94,8 @@ (ALSA device hw:1,0). For saa7134-based cards either the saa7134-alsa or saa7134-oss module must be loaded. <screen> -mplayer -rawaudio rate=32000 -radio adevice=hw=1.0:arate=32000:channels=104.4=Sibir,103.9=Maximm radio://2/capture +mplayer -rawaudio rate=32000 radio://2/capture \ + -radio adevice=hw=1.0:arate=32000:channels=104.4=Sibir,103.9=Maximm </screen> <note><para>When using ALSA device names colons must be replaced by equal signs, commas by periods.
--- a/DOCS/xml/en/skin.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/skin.xml Fri Dec 08 11:38:06 2006 +0000 @@ -5,33 +5,39 @@ <sect1 id="skin-overview"> <title>Overview</title> + <para> It does not really have anything to do with the skin format, but you should -know that <application>MPlayer</application> has <emphasis role="bold">no</emphasis> -builtin skin, so <emphasis role="bold">at least one skin must be installed -in order to be able to use the GUI.</emphasis> +know that <application>MPlayer</application> has +<emphasis role="bold">no</emphasis> builtin skin, so +<emphasis role="bold">at least one skin must be installed in order to be able +to use the GUI.</emphasis> </para> +<!-- ********** --> + <sect2 id="skin-overview-directories"> <title>Directories</title> + <para> The directories searched for skins are (in order): <orderedlist> <listitem><para> -<filename class="directory">$(DATADIR)/skins/</filename> + <filename class="directory">$(DATADIR)/skins/</filename> </para></listitem> <listitem><para> -<filename class="directory">$(PREFIX)/share/mplayer/skins/</filename> + <filename class="directory">$(PREFIX)/share/mplayer/skins/</filename> </para></listitem> <listitem><para> -<filename class="directory">~/.mplayer/skins/</filename> + <filename class="directory">~/.mplayer/skins/</filename> </para></listitem> </orderedlist> </para> <para> -Note that the first path may vary according to the way <application>MPlayer</application> -was configured (see the <option>--prefix</option> and <option>--datadir</option> +Note that the first path may vary according to the way +<application>MPlayer</application> was configured (see the +<option>--prefix</option> and <option>--datadir</option> arguments of the <command>configure</command> script). </para> @@ -42,8 +48,11 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="skin-overview-formats"> <title>Image formats</title> + <para>Images must be truecolor (24 or 32 bpp) PNGs.</para> <para> In the main window and in the playbar (see below) you can use images with @@ -55,6 +64,7 @@ <sect2 id="skin-overview-components"> <title>Skin components</title> + <para> Skins are quite free-format (unlike the fixed-format skins of <application>Winamp</application>/<application>XMMS</application>, @@ -70,48 +80,61 @@ by a right click). <itemizedlist> -<listitem><para> +<listitem> + <para> The <emphasis role="bold">main window</emphasis> and/or the <emphasis role="bold">playbar</emphasis> is where you can control <application>MPlayer</application>. The background of the window is an image. - Various items can (and must) be placed in the window: <emphasis>buttons</emphasis>, - <emphasis>potmeters</emphasis> (sliders) and <emphasis>labels</emphasis>. + Various items can (and must) be placed in the window: + <emphasis>buttons</emphasis>, <emphasis>potmeters</emphasis> (sliders) and + <emphasis>labels</emphasis>. For every item, you must specify its position and size. -</para><para> + </para> + + <para> A <emphasis role="bold">button</emphasis> has three states (pressed, released, disabled), thus its image must be divided into three parts vertically. See the <link linkend="skin-button">button</link> item for details. -</para><para> + </para> + + <para> A <emphasis role="bold">potmeter</emphasis> (mainly used for the seek bar and volume/balance control) can have any number of phases by dividing its image into different parts below each other. See <link linkend="skin-hpotmeter">hpotmeter</link> and <link linkend="skin-potmeter">potmeter</link> for details. -</para><para> + </para> + + <para> <emphasis role="bold">Labels</emphasis> are a bit special: The characters needed to draw them are taken from an image file, and the characters in the - image are described by a <link linkend="skin-fonts">font description file</link>. + image are described by a + <link linkend="skin-fonts">font description file</link>. The latter is a plain text file which specifies the x,y position and size of each character in the image (the image file and its font description file - form a font <emphasis>together</emphasis>). See <link linkend="skin-dlabel">dlabel</link> + form a font <emphasis>together</emphasis>). + See <link linkend="skin-dlabel">dlabel</link> and <link linkend="skin-slabel">slabel</link> for details. -</para> -<note><para>All images can have full transparency as described in the section about + </para> + + <note><para> + All images can have full transparency as described in the section about <link linkend="skin-overview-formats">image formats</link>. If the X server doesn't support the XShape extension, the parts marked transparent will be black. If you'd like to use this feature, the width of the main window's background image must be dividable by 8. -</para></note> + </para></note> </listitem> <listitem><para> The <emphasis role="bold">subwindow</emphasis> is where the movie appears. It can display a specified image if there is no movie loaded (it is quite boring - to have an empty window :-)) <emphasis role="bold">Note:</emphasis> transparency - is <emphasis role="bold">not allowed</emphasis> here. + to have an empty window :-)) <emphasis role="bold">Note:</emphasis> + transparency is <emphasis role="bold">not allowed</emphasis> here. </para></listitem> -<listitem><para> +<listitem> + <para> The <emphasis role="bold">skin menu</emphasis> is just a way to control <application>MPlayer</application> by means of menu entries. Two images are required for the menu: one of them is the base image that shows the @@ -120,24 +143,30 @@ the mouse over the menu entries, the currently selected entry is copied from the second image over the menu entry below the mouse pointer (the second image is never shown as a whole). -</para><para> + </para> + <para> A menu entry is defined by its position and size in the image (see the - section about the <link linkend="skin-file-menu">skin menu</link> for details). -</para></listitem> + section about the <link linkend="skin-file-menu">skin menu</link> for + details). + </para> +</listitem> </itemizedlist> </para> <para> - There is an important thing not mentioned yet: For buttons, potmeters and - menu entries to work, <application>MPlayer</application> must know what to - do if they are clicked. This is done by <link linkend="skin-gui">messages</link> - (events). For these items you must define the messages to be generated when - they are clicked. +There is an important thing not mentioned yet: For buttons, potmeters and +menu entries to work, <application>MPlayer</application> must know what to +do if they are clicked. This is done by <link linkend="skin-gui">messages</link> +(events). For these items you must define the messages to be generated when +they are clicked. </para> </sect2> +<!-- ********** --> + <sect2 id="skin-files"> <title>Files</title> + <para> You need the following files to build a skin: <itemizedlist> @@ -168,12 +197,17 @@ </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="skin-file"> <title>The skin file</title> + <para> As mentioned above, this is the skin configuration file. It is line oriented; -comment lines start with a '<literal>;</literal>' character at the beginning -of the line (only spaces and tabs are allowed before the '<literal>;</literal>'). +comment lines start with a '<literal>;</literal>' character at the beginning of +the line (only spaces and tabs are allowed before the '<literal>;</literal>'). </para> <para> @@ -189,8 +223,8 @@ </para> <para> -Currently there is only one application, so you need only one section: its name is -<emphasis role="bold">movieplayer</emphasis>. +Currently there is only one application, so you need only one section: its name +is <emphasis role="bold">movieplayer</emphasis>. </para> <para> @@ -207,10 +241,18 @@ <para> where <replaceable>window name</replaceable> can be one of these strings: <itemizedlist> -<listitem><para><emphasis role="bold">main</emphasis> - for the main window</para></listitem> -<listitem><para><emphasis role="bold">sub</emphasis> - for the subwindow</para></listitem> -<listitem><para><emphasis role="bold">menu</emphasis> - for the skin menu</para></listitem> -<listitem><para><emphasis role="bold">playbar</emphasis> - playbar</para></listitem> +<listitem><para> + <emphasis role="bold">main</emphasis> - for the main window +</para></listitem> +<listitem><para> + <emphasis role="bold">sub</emphasis> - for the subwindow +</para></listitem> +<listitem><para> + <emphasis role="bold">menu</emphasis> - for the skin menu +</para></listitem> +<listitem><para> + <emphasis role="bold">playbar</emphasis> - playbar +</para></listitem> </itemizedlist> </para> @@ -262,12 +304,19 @@ </para> <para> -Finally some words about positioning. The main window and the subwindow can -be placed in the different corners of the screen by giving <literal>X</literal> and -<literal>Y</literal> coordinates. <literal>0</literal> is top or left, +Here is an example to make this clear. Suppose that you have an image called +<filename>main.png</filename> that you use for the main window: +<programlisting>base = main, -1, -1</programlisting> +<application>MPlayer</application> tries to load <filename>main</filename>, +<filename>main.png</filename>, <filename>main.PNG</filename> files. +</para> + +<para> +Finally some words about positioning. The main window and the subwindow can be +placed in the different corners of the screen by giving <literal>X</literal> +and <literal>Y</literal> coordinates. <literal>0</literal> is top or left, <literal>-1</literal> is center and <literal>-2</literal> is right or bottom, as shown in this illustration: -</para> <informalfigure> <screen> (0, 0)----(-1, 0)----(-2, 0) @@ -279,18 +328,13 @@ (0,-2)----(-1,-2)----(-2,-2) </screen> </informalfigure> - -<para> -Here is an example to make this clear. Suppose that you have an image called -<filename>main.png</filename> that you use for the main window: -<programlisting>base = main, -1, -1</programlisting> -<application>MPlayer</application> tries to load <filename>main</filename>, -<filename>main.png</filename>, <filename>main.PNG</filename> files. </para> +<!-- ********** --> <sect2 id="skin-file-main"> <title>Main window and playbar</title> + <para> Below is the list of entries that can be used in the '<literal>window = main</literal>' ... '<literal>end</literal>', @@ -303,40 +347,44 @@ <term><literal> <anchor id="skin-main-base"/>base = image, X, Y </literal></term> - <listitem><para> -Lets you specify the background image to be used for the main window. -The window will appear at the given <literal>X,Y</literal> position on -the screen The window will have the size of the image. - </para> - <note><para>These coordinates do not currently work for the display window.</para></note> - <warning><para>Transparent regions in the image (colored #FF00FF) appear black - on X servers without the XShape extension. The image's width must be dividable - by 8.</para></warning> - </listitem> + <listitem> + <para> + Lets you specify the background image to be used for the main window. + The window will appear at the given <literal>X,Y</literal> position on + the screen The window will have the size of the image. + </para> + <note><para> + These coordinates do not currently work for the display window. + </para></note> + <warning><para>Transparent regions in the image (colored #FF00FF) appear black + on X servers without the XShape extension. The image's width must be dividable + by 8.</para></warning> + </listitem> </varlistentry> <varlistentry> <term><literal> <anchor id="skin-button"/>button = image, X, Y, width, height, message </literal></term> - <listitem><para> -Place a button of <literal>width</literal> * <literal>height</literal> size at -position <literal>X,Y</literal>. The specified <literal>message</literal> is -generated when the button is clicked. The image given by <literal>image</literal> -must have three parts below each other (according to the possible states of the -button), like this: -</para> -<informalfigure> -<screen> + <listitem> + <para> + Place a button of <literal>width</literal> * <literal>height</literal> size at + position <literal>X,Y</literal>. The specified <literal>message</literal> is + generated when the button is clicked. The image given by + <literal>image</literal> must have three parts below each other (according to + the possible states of the button), like this: + </para> + <informalfigure> + <screen> +------------+ | pressed | +------------+ | released | +------------+ | disabled | -+------------+ -</screen> -</informalfigure> ++------------+<!-- + --></screen> + </informalfigure> </listitem> </varlistentry> @@ -344,11 +392,14 @@ <term><literal> <anchor id="skin-decoration"/>decoration = enable|disable </literal></term> - <listitem><para> -Enable or disable window manager decoration of the main window. Default is -<emphasis role="bold">disable</emphasis>. - </para> - <note><para>This doesn't work for the display window, there is no need to.</para></note> + <listitem> + <para> + Enable or disable window manager decoration of the main window. Default is + <emphasis role="bold">disable</emphasis>. + </para> + <note><para> + This doesn't work for the display window, there is no need to. + </para></note> </listitem> </varlistentry> @@ -357,8 +408,7 @@ <anchor id="skin-hpotmeter"/>hpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message </literal></term> <listitem><para> - - </para></listitem> + </para></listitem> </varlistentry> <varlistentry> @@ -366,29 +416,29 @@ <anchor id="skin-vpotmeter"/>vpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message </literal></term> <listitem><para> -Place a horizontal (hpotmeter) or vertical (vpotmeter) potmeter of -<literal>width</literal> * <literal>height</literal> size at position -<literal>X,Y</literal>. The image can be divided into different parts for the -different phases of the potmeter (for example, you can have a pot for volume -control that turns from green to red while its value changes from the minimum -to the maximum.). <literal>hpotmeter</literal> can have a button that can be -dragged horizontally. The parameters are: - </para> - <itemizedlist> - <listitem><para><literal>button</literal> - the image to be used for the + Place a horizontal (hpotmeter) or vertical (vpotmeter) potmeter of + <literal>width</literal> * <literal>height</literal> size at position + <literal>X,Y</literal>. The image can be divided into different parts for the + different phases of the potmeter (for example, you can have a pot for volume + control that turns from green to red while its value changes from the minimum + to the maximum.). <literal>hpotmeter</literal> can have a button that can be + dragged horizontally. The parameters are: + <itemizedlist> + <listitem><para> + <literal>button</literal> - the image to be used for the button (must have three parts below each other, like in case of <link linkend="skin-button">button</link>) - </para></listitem> - <listitem><para><literal>bwidth</literal>, <literal>bheight</literal> - size + </para></listitem> + <listitem><para> + <literal>bwidth</literal>, <literal>bheight</literal> - size of the button - </para></listitem> - <listitem><para><literal>phases</literal> - the image to be used for the - different phases of the hpotmeter. A special value of <literal>NULL</literal> - can be used if you want no such image. The image must be divided into - <literal>numphases</literal> parts vertically like this: - </para> -<informalfigure> -<screen> + </para></listitem> + <listitem><para> + <literal>phases</literal> - the image to be used for the + different phases of the hpotmeter. A special value of <literal>NULL</literal> + can be used if you want no such image. The image must be divided into + <literal>numphases</literal> parts vertically like this: + <informalfigure><screen> +------------+ | phase #1 | +------------+ @@ -397,27 +447,30 @@ ... +------------+ | phase #n | -+------------+ -</screen> -</informalfigure> - </listitem> - <listitem><para><literal>numphases</literal> - number of phases stored in the ++------------+<!-- + --></screen></informalfigure> + </para></listitem> + <listitem><para> + <literal>numphases</literal> - number of phases stored in the <literal>phases</literal> image - </para></listitem> - <listitem><para><literal>default</literal> - default value for hpotmeter + </para></listitem> + <listitem><para> + <literal>default</literal> - default value for hpotmeter (in the range <literal>0</literal> to <literal>100</literal>) - </para></listitem> - <listitem><para><literal>X</literal>, <literal>Y</literal> - position for the hpotmeter - </para></listitem> - <listitem><para><literal>width</literal>, <literal>height</literal> - width and height + </para></listitem> + <listitem><para> + <literal>X</literal>, <literal>Y</literal> - position for the hpotmeter + </para></listitem> + <listitem><para> + <literal>width</literal>, <literal>height</literal> - width and height of the <literal>hpotmeter</literal> - </para></listitem> - <listitem><para><literal>message</literal> - the message to be generated when the + </para></listitem> + <listitem><para> + <literal>message</literal> - the message to be generated when the value of <literal>hpotmeter</literal> is changed - </para></listitem> - </itemizedlist> - - </listitem> + </para></listitem> + </itemizedlist> + </para></listitem> </varlistentry> <varlistentry> @@ -425,12 +478,12 @@ <anchor id="skin-potmeter"/>potmeter = phases, numphases, default, X, Y, width, height, message </literal></term> <listitem><para> -A <literal>hpotmeter</literal> without a button. (I guess it is meant to be -turned around, but it reacts to horizontal dragging only.) For the description -of the parameters see <link linkend="skin-hpotmeter">hpotmeter</link>. -<literal>phases</literal> can be <literal>NULL</literal>, but it is quite useless, -since you cannot see where the <literal>potmeter</literal> is set. - </para></listitem> + A <literal>hpotmeter</literal> without a button. (I guess it is meant to be + turned around, but it reacts to horizontal dragging only.) For the description + of the parameters see <link linkend="skin-hpotmeter">hpotmeter</link>. + <literal>phases</literal> can be <literal>NULL</literal>, but it is quite + useless, since you cannot see where the <literal>potmeter</literal> is set. + </para></listitem> </varlistentry> <varlistentry> @@ -438,11 +491,12 @@ <anchor id="skin-font"/>font = fontfile, fontid </literal></term> <listitem><para> -Defines a font. <literal>fontfile</literal> is the name of a font description file -with a <filename>.fnt</filename> extension (do not specify the extension here). -<literal>fontid</literal> is used to refer to the font (see <link linkend="skin-dlabel">dlabel</link> -and <link linkend="skin-slabel">slabel</link>). Up to 25 fonts can be defined. - </para></listitem> + Defines a font. <literal>fontfile</literal> is the name of a font description + file with a <filename>.fnt</filename> extension (do not specify the extension + here). <literal>fontid</literal> is used to refer to the font + (see <link linkend="skin-dlabel">dlabel</link> + and <link linkend="skin-slabel">slabel</link>). Up to 25 fonts can be defined. + </para></listitem> </varlistentry> <varlistentry> @@ -450,12 +504,13 @@ <anchor id="skin-slabel"/>slabel = X, Y, fontid, "text" </literal></term> <listitem><para> -Place a static label at the position <literal>X,Y</literal>. <literal>text</literal> -is displayed using the font identified by <literal>fontid</literal>. The text is -just a raw string (<literal>$x</literal> variables do not work) that must be enclosed -between double quotes (but the " character cannot be part of the text). The -label is displayed using the font identified by <literal>fontid</literal>. - </para></listitem> + Place a static label at the position <literal>X,Y</literal>. + <literal>text</literal> is displayed using the font identified by + <literal>fontid</literal>. The text is just a raw string + (<literal>$x</literal> variables do not work) that must be enclosed between + double quotes (but the " character cannot be part of the text). The + label is displayed using the font identified by <literal>fontid</literal>. + </para></listitem> </varlistentry> <varlistentry> @@ -463,154 +518,159 @@ <anchor id="skin-dlabel"/>dlabel = X, Y, length, align, fontid, "text" </literal></term> <listitem> -<para> -Place a dynamic label at the position <literal>X,Y</literal>. The label is called -dynamic because its text is refreshed periodically. The maximum length of the -label is given by <literal>length</literal> (its height is the height of a -character). If the text to be displayed is wider than that, it will be scrolled, -otherwise it is aligned within the specified space by the value of the -<literal>align</literal> parameter: <literal>0</literal> is for right, -<literal>1</literal> is for center, <literal>2</literal> is for left. -</para> -<para> -The text to be displayed is given by <literal>text</literal>: It must be written -between double quotes (but the " character cannot be part of the text). The -label is displayed using the font identified by <literal>fontid</literal>. You -can use the following variables in the text: -</para> + <para> + Place a dynamic label at the position <literal>X,Y</literal>. The label is + called dynamic because its text is refreshed periodically. The maximum length + of the label is given by <literal>length</literal> (its height is the height + of a character). If the text to be displayed is wider than that, it will be + scrolled, + otherwise it is aligned within the specified space by the value of the + <literal>align</literal> parameter: <literal>0</literal> is for right, + <literal>1</literal> is for center, <literal>2</literal> is for left. + </para> + <para> + The text to be displayed is given by <literal>text</literal>: It must be + written between double quotes (but the " character cannot be part of the + text). The label is displayed using the font identified by + <literal>fontid</literal>. You can use the following variables in the text: + </para> -<informaltable> -<tgroup cols="2"> -<thead> - <row><entry>Variable</entry><entry>Meaning</entry></row> -</thead> -<tbody> -<row> -<entry>$1</entry> -<entry>play time in <emphasis>hh:mm:ss</emphasis> format</entry> -</row> -<row> -<entry>$2</entry> -<entry>play time in <emphasis>mmmm:ss</emphasis> format</entry> -</row> -<row> -<entry>$3</entry> -<entry>play time in <emphasis>hh</emphasis> format (hours)</entry> -</row> -<row> -<entry>$4</entry> -<entry>play time in <emphasis>mm</emphasis> format (minutes)</entry> -</row> -<row> -<entry>$5</entry> -<entry>play time in <emphasis>ss</emphasis> format (seconds)</entry> -</row> -<row> -<entry>$6</entry> -<entry>movie length in <emphasis>hh:mm:ss</emphasis> format</entry> -</row> -<row> -<entry>$7</entry> -<entry>movie length in <emphasis>mmmm:ss</emphasis> format</entry> -</row> -<row> -<entry>$8</entry> -<entry>play time in <emphasis>h:mm:ss</emphasis> format</entry> -</row> -<row> -<entry>$v</entry> -<entry>volume in <emphasis>xxx.xx</emphasis>% format</entry> -</row> -<row> -<entry>$V</entry> -<entry>volume in <emphasis>xxx.xx</emphasis> format</entry> -</row> -<row> -<entry>$b</entry> -<entry>balance in <emphasis>xxx.xx</emphasis>% format</entry> -</row> -<row> -<entry>$B</entry> -<entry>balance in <emphasis>xxx.xx</emphasis> format</entry> -</row> -<row> -<entry>$$</entry> -<entry>the $ character</entry> -</row> -<row> -<entry>$a</entry> -<entry>a character according to the audio type (none: <literal>n</literal>, -mono: <literal>m</literal>, stereo: <literal>t</literal>)</entry> -</row> -<row> -<entry>$t</entry> -<entry>track number (in playlist)</entry> -</row> -<row> -<entry>$o</entry> -<entry>filename</entry> -</row> -<row> -<entry>$f</entry> -<entry>filename in lower case</entry> -</row> -<row> -<entry>$F</entry> -<entry>filename in upper case</entry> -</row> -<row> -<entry>$T</entry> -<entry>a character according to the stream type (file: <literal>f</literal>, -Video CD: <literal>v</literal>, DVD: <literal>d</literal>, URL: <literal>u</literal>)</entry> -</row> -<row> -<entry>$p</entry> -<entry>the <keycap>p</keycap> character (if a movie is playing and the font has -the <keycap>p</keycap> character)</entry> -</row> -<row> -<entry>$s</entry> -<entry>the <keycap>s</keycap> character (if the movie is stopped and the font has -the <keycap>s</keycap> character)</entry> -</row> -<row> -<entry>$e</entry> -<entry>the <keycap>e</keycap> character (if playback is paused and the font has -the <keycap>e</keycap> character)</entry> -</row> -<row> -<entry>$x</entry> -<entry>movie width</entry> -</row> -<row> -<entry>$y</entry> -<entry>movie height</entry> -</row> -<row> -<entry>$C</entry> -<entry>name of the codec used</entry> -</row> + <informaltable> + <tgroup cols="2"> + <thead> + <row><entry>Variable</entry><entry>Meaning</entry></row> + </thead> + <tbody> + <row> + <entry>$1</entry> + <entry>play time in <emphasis>hh:mm:ss</emphasis> format</entry> + </row> + <row> + <entry>$2</entry> + <entry>play time in <emphasis>mmmm:ss</emphasis> format</entry> + </row> + <row> + <entry>$3</entry> + <entry>play time in <emphasis>hh</emphasis> format (hours)</entry> + </row> + <row> + <entry>$4</entry> + <entry>play time in <emphasis>mm</emphasis> format (minutes)</entry> + </row> + <row> + <entry>$5</entry> + <entry>play time in <emphasis>ss</emphasis> format (seconds)</entry> + </row> + <row> + <entry>$6</entry> + <entry>movie length in <emphasis>hh:mm:ss</emphasis> format</entry> + </row> + <row> + <entry>$7</entry> + <entry>movie length in <emphasis>mmmm:ss</emphasis> format</entry> + </row> + <row> + <entry>$8</entry> + <entry>play time in <emphasis>h:mm:ss</emphasis> format</entry> + </row> + <row> + <entry>$v</entry> + <entry>volume in <emphasis>xxx.xx</emphasis>% format</entry> + </row> + <row> + <entry>$V</entry> + <entry>volume in <emphasis>xxx.xx</emphasis> format</entry> + </row> + <row> + <entry>$b</entry> + <entry>balance in <emphasis>xxx.xx</emphasis>% format</entry> + </row> + <row> + <entry>$B</entry> + <entry>balance in <emphasis>xxx.xx</emphasis> format</entry> + </row> + <row> + <entry>$$</entry> + <entry>the $ character</entry> + </row> + <row> + <entry>$a</entry> + <entry>a character according to the audio type (none: <literal>n</literal>, + mono: <literal>m</literal>, stereo: <literal>t</literal>)</entry> + </row> + <row> + <entry>$t</entry> + <entry>track number (in playlist)</entry> + </row> + <row> + <entry>$o</entry> + <entry>filename</entry> + </row> + <row> + <entry>$f</entry> + <entry>filename in lower case</entry> + </row> + <row> + <entry>$F</entry> + <entry>filename in upper case</entry> + </row> + <row> + <entry>$T</entry> + <entry> + a character according to the stream type (file: <literal>f</literal>, + Video CD: <literal>v</literal>, DVD: <literal>d</literal>, + URL: <literal>u</literal>) + </entry> + </row> + <row> + <entry>$p</entry> + <entry>the <keycap>p</keycap> character (if a movie is playing and the font + has the <keycap>p</keycap> character)</entry> + </row> + <row> + <entry>$s</entry> + <entry>the <keycap>s</keycap> character (if the movie is stopped and the + font has the <keycap>s</keycap> character)</entry> + </row> + <row> + <entry>$e</entry> + <entry>the <keycap>e</keycap> character (if playback is paused and the font + has the <keycap>e</keycap> character)</entry> + </row> + <row> + <entry>$x</entry> + <entry>movie width</entry> + </row> + <row> + <entry>$y</entry> + <entry>movie height</entry> + </row> + <row> + <entry>$C</entry> + <entry>name of the codec used</entry> + </row> + </tbody> + </tgroup> + </informaltable> -</tbody> -</tgroup> -</informaltable> -</listitem> - + <note><para> + The <literal>$a, $T, $p, $s</literal> and <literal>$e</literal> + variables all return characters that should be displayed as special symbols + (for example, <keycap>e</keycap> is for the pause symbol that usually looks + something like ||). You should have a font for normal characters and + a different font for symbols. See the section about + <link linkend="skin-fonts-symbols">symbols</link> for more information. + </para></note> + </listitem> </varlistentry> </variablelist> +</sect2> -<note><para> -The <literal>$a, $T, $p, $s</literal> and <literal>$e</literal> -variables all return characters that should be displayed as special symbols (for -example, <keycap>e</keycap> is for the pause symbol that usually looks something -like ||). You should have a font for normal characters and a different font for -symbols. See the section about <link linkend="skin-fonts-symbols">symbols</link> -for more information. -</para></note> -</sect2> +<!-- ********** --> <sect2 id="skin-file-subwindow"> <title>Subwindow</title> + <para> The following entries can be used in the '<literal>window = sub</literal>' . . . '<literal>end</literal>' block. @@ -622,14 +682,15 @@ <anchor id="skin-sub-base"/>base = image, X, Y, width, height </literal></term> <listitem><para> -The image to be displayed in the window. The window will appear at the given -<literal>X,Y</literal> position on the screen (<literal>0,0</literal> is the -top left corner). You can specify <literal>-1</literal> for center and <literal>-2</literal> -for right (<literal>X</literal>) and bottom (<literal>Y</literal>). The window -will be as large as the image. <literal>width</literal> and <literal>height</literal> -denote the size of the window; they are optional (if they are missing, the -window is the same size as the image). - </para></listitem> + The image to be displayed in the window. The window will appear at the given + <literal>X,Y</literal> position on the screen (<literal>0,0</literal> is the + top left corner). You can specify <literal>-1</literal> for center and + <literal>-2</literal> for right (<literal>X</literal>) and bottom + (<literal>Y</literal>). The window will be as large as the image. + <literal>width</literal> and <literal>height</literal> + denote the size of the window; they are optional (if they are missing, the + window is the same size as the image). + </para></listitem> </varlistentry> <varlistentry> @@ -637,17 +698,20 @@ <anchor id="skin-background"/>background = R, G, B </literal></term> <listitem><para> -Lets you set the background color. It is useful if the image is smaller than -the window. <literal>R</literal>, <literal>G</literal> and <literal>B</literal> -specifies the red, green and blue component of the color (each of them is a -decimal number from 0 to 255). - </para></listitem> + Lets you set the background color. It is useful if the image is smaller than + the window. <literal>R</literal>, <literal>G</literal> and + <literal>B</literal> specifies the red, green and blue component of the color + (each of them is a decimal number from 0 to 255). + </para></listitem> </varlistentry> </variablelist> </sect2> +<!-- ********** --> + <sect2 id="skin-file-menu"> <title>Skin menu</title> + <para> As mentioned earlier, the menu is displayed using two images. Normal menu entries are taken from the image specified by the <literal>base</literal> item, @@ -667,8 +731,8 @@ <anchor id="skin-menu-base"/>base = image </literal></term> <listitem><para> -The image for normal menu entries. - </para></listitem> + The image for normal menu entries. + </para></listitem> </varlistentry> <varlistentry> @@ -676,8 +740,8 @@ <anchor id="skin-selected"/>selected = image </literal></term> <listitem><para> -The image showing the menu with all entries selected. - </para></listitem> + The image showing the menu with all entries selected. + </para></listitem> </varlistentry> <varlistentry> @@ -685,22 +749,26 @@ <anchor id="skin-menu"/>menu = X, Y, width, height, message </literal></term> <listitem><para> -Defines the <literal>X,Y</literal> position and the size of a menu entry in -the image. <literal>message</literal> is the message to be generated when the -mouse button is released over the entry. - </para></listitem> + Defines the <literal>X,Y</literal> position and the size of a menu entry in + the image. <literal>message</literal> is the message to be generated when the + mouse button is released over the entry. + </para></listitem> </varlistentry> </variablelist> </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="skin-fonts"> <title>Fonts</title> <para> As mentioned in the section about the parts of a skin, a font is defined by an -image and a description file. You can place the characters anywhere in the image, -but make sure that their position and size is given in the description file -exactly. +image and a description file. You can place the characters anywhere in the +image, but make sure that their position and size is given in the description +file exactly. </para> <para> @@ -732,14 +800,18 @@ </programlisting> </para> +<!-- ********** --> + <sect2 id="skin-fonts-symbols"> <title>Symbols</title> + <para> Some characters have special meanings when returned by some of the variables used in <link linkend="skin-dlabel">dlabel</link>. These characters are meant to be shown as symbols so that things like a nice DVD logo can be displayed instead of the character '<literal>d</literal>' for a DVD stream. </para> + <para> The following table lists all the characters that can be used to display symbols (and thus require a different font). @@ -751,24 +823,29 @@ <row><entry>Character</entry><entry>Symbol</entry></row> </thead> <tbody> -<row><entry><keycap>p</keycap></entry><entry>play</entry></row> -<row><entry><keycap>s</keycap></entry><entry>stop</entry></row> -<row><entry><keycap>e</keycap></entry><entry>pause</entry></row> -<row><entry><keycap>n</keycap></entry><entry>no sound</entry></row> -<row><entry><keycap>m</keycap></entry><entry>mono sound</entry></row> -<row><entry><keycap>t</keycap></entry><entry>stereo sound</entry></row> -<row><entry><keycap>f</keycap></entry><entry>stream is a file</entry></row> -<row><entry><keycap>v</keycap></entry><entry>stream is a Video CD</entry></row> -<row><entry><keycap>d</keycap></entry><entry>stream is a DVD</entry></row> -<row><entry><keycap>u</keycap></entry><entry>stream is a URL</entry></row> + <row><entry><keycap>p</keycap></entry><entry>play</entry></row> + <row><entry><keycap>s</keycap></entry><entry>stop</entry></row> + <row><entry><keycap>e</keycap></entry><entry>pause</entry></row> + <row><entry><keycap>n</keycap></entry><entry>no sound</entry></row> + <row><entry><keycap>m</keycap></entry><entry>mono sound</entry></row> + <row><entry><keycap>t</keycap></entry><entry>stereo sound</entry></row> + <row><entry><keycap>f</keycap></entry><entry>stream is a file</entry></row> + <row><entry><keycap>v</keycap></entry><entry>stream is a Video CD</entry></row> + <row><entry><keycap>d</keycap></entry><entry>stream is a DVD</entry></row> + <row><entry><keycap>u</keycap></entry><entry>stream is a URL</entry></row> </tbody> </tgroup> </informaltable> </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="skin-gui"> <title>GUI messages</title> + <para> These are the messages that can be generated by buttons, potmeters and menu entries. @@ -779,49 +856,50 @@ <varlistentry> <term><emphasis role="bold">evNext</emphasis></term> <listitem><para> -Jump to next track in the playlist. - </para></listitem> + Jump to next track in the playlist. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPause</emphasis></term> <listitem><para> -Forms a switch together with <literal>evPlaySwitchToPause</literal>. They can -be used to have a common play/pause button. Both messages should be assigned to -buttons displayed at the very same position in the window. This message pauses -playing and the image for the <literal>evPlaySwitchToPause</literal> button is -displayed (to indicate that the button can be pressed to continue playing). - </para></listitem> + Forms a switch together with <literal>evPlaySwitchToPause</literal>. They can + be used to have a common play/pause button. Both messages should be assigned + to buttons displayed at the very same position in the window. This message + pauses playing and the image for the <literal>evPlaySwitchToPause</literal> + button is displayed (to indicate that the button can be pressed to continue + playing). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlay</emphasis></term> <listitem><para> -Start playing. - </para></listitem> + Start playing. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlaySwitchToPause</emphasis></term> <listitem><para> -The opposite of <literal>evPauseSwitchToPlay</literal>. This message starts -playing and the image for the <literal>evPauseSwitchToPlay</literal> button -is displayed (to indicate that the button can be pressed to pause playing). - </para></listitem> + The opposite of <literal>evPauseSwitchToPlay</literal>. This message starts + playing and the image for the <literal>evPauseSwitchToPlay</literal> button + is displayed (to indicate that the button can be pressed to pause playing). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPrev</emphasis></term> <listitem><para> -Jump to previous track in the playlist. - </para></listitem> + Jump to previous track in the playlist. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evStop</emphasis></term> <listitem><para> -Stop playing. - </para></listitem> + Stop playing. + </para></listitem> </varlistentry> </variablelist> @@ -830,51 +908,51 @@ <varlistentry> <term><emphasis role="bold">evBackward10sec</emphasis></term> <listitem><para> -Seek backward 10 seconds. - </para></listitem> + Seek backward 10 seconds. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evBackward1min</emphasis></term> <listitem><para> -Seek backward 1 minute. - </para></listitem> + Seek backward 1 minute. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evBackward10min</emphasis></term> <listitem><para> -Seek backward 10 minutes. - </para></listitem> + Seek backward 10 minutes. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evForward10sec</emphasis></term> <listitem><para> -Seek forward 10 seconds. - </para></listitem> + Seek forward 10 seconds. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evForward1min</emphasis></term> <listitem><para> -Seek forward 1 minute. - </para></listitem> + Seek forward 1 minute. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evForward10min</emphasis></term> <listitem><para> -Seek forward 10 minutes. - </para></listitem> + Seek forward 10 minutes. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetMoviePosition</emphasis></term> <listitem><para> -Seek to position (can be used by a potmeter; the -relative value (0-100%) of the potmeter is used). - </para></listitem> + Seek to position (can be used by a potmeter; the + relative value (0-100%) of the potmeter is used). + </para></listitem> </varlistentry> </variablelist> @@ -883,26 +961,26 @@ <varlistentry> <term><emphasis role="bold">evHalfSize</emphasis></term> <listitem><para> -Set the movie window to half size. - </para></listitem> + Set the movie window to half size. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDoubleSize</emphasis></term> <listitem><para> -Set the movie window to double size. - </para></listitem> + Set the movie window to double size. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evFullScreen</emphasis></term> <listitem><para> -Switch fullscreen mode on/off. - </para></listitem> + Switch fullscreen mode on/off. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evNormalSize</emphasis></term> <listitem><para> -Set the movie window to its normal size. - </para></listitem> + Set the movie window to its normal size. + </para></listitem> </varlistentry> </variablelist> @@ -911,66 +989,66 @@ <varlistentry> <term><emphasis role="bold">evDecAudioBufDelay</emphasis></term> <listitem><para> -Decrease audio buffer delay. - </para></listitem> + Decrease audio buffer delay. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDecBalance</emphasis></term> <listitem><para> -Decrease balance. - </para></listitem> + Decrease balance. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDecVolume</emphasis></term> <listitem><para> -Decrease volume. - </para></listitem> + Decrease volume. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIncAudioBufDelay</emphasis></term> <listitem><para> -Increase audio buffer delay. - </para></listitem> + Increase audio buffer delay. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIncBalance</emphasis></term> <listitem><para> -Increase balance. - </para></listitem> + Increase balance. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIncVolume</emphasis></term> <listitem><para> -Increase volume. - </para></listitem> + Increase volume. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evMute</emphasis></term> <listitem><para> -Mute/unmute the sound. - </para></listitem> + Mute/unmute the sound. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetBalance</emphasis></term> <listitem><para> -Set balance (can be used by a potmeter; the -relative value (0-100%) of the potmeter is used). - </para></listitem> + Set balance (can be used by a potmeter; the + relative value (0-100%) of the potmeter is used). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetVolume</emphasis></term> <listitem><para> -Set volume (can be used by a potmeter; the relative -value (0-100%) of the potmeter is used). - </para></listitem> + Set volume (can be used by a potmeter; the relative + value (0-100%) of the potmeter is used). + </para></listitem> </varlistentry> </variablelist> @@ -979,125 +1057,128 @@ <varlistentry> <term><emphasis role="bold">evAbout</emphasis></term> <listitem><para> -Open the about window. - </para></listitem> + Open the about window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDropSubtitle</emphasis></term> <listitem><para> -Disables the currently used subtitle. - </para></listitem> + Disables the currently used subtitle. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evEqualizer</emphasis></term> <listitem><para> -Turn the equalizer on/off. - </para></listitem> + Turn the equalizer on/off. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evExit</emphasis></term> <listitem><para> -Quit the program. - </para></listitem> + Quit the program. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIconify</emphasis></term> <listitem><para> -Iconify the window. - </para></listitem> + Iconify the window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoad</emphasis></term> <listitem><para> -Load a file (by opening a file browser window, where you can choose a file). - </para></listitem> + Load a file (by opening a file browser window, where you can choose a file). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoadPlay</emphasis></term> <listitem><para> -Does the same as <literal>evLoad</literal>, but it automatically starts playing after -the file is loaded. - </para></listitem> + Does the same as <literal>evLoad</literal>, but it automatically starts + playing after the file is loaded. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoadSubtitle</emphasis></term> <listitem><para> -Loads a subtitle file (with the fileselector) - </para></listitem> + Loads a subtitle file (with the fileselector) + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoadAudioFile</emphasis></term> <listitem><para> -Loads an audio file (with the fileselector) - </para></listitem> + Loads an audio file (with the fileselector) + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evNone</emphasis></term> <listitem><para> -Empty message, it has no effect (except maybe in Subversion versions :-)). - </para></listitem> + Empty message, it has no effect (except maybe in Subversion versions :-)). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlaylist</emphasis></term> <listitem><para> -Open/close the playlist window. - </para></listitem> + Open/close the playlist window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlayDVD</emphasis></term> <listitem><para> -Tries to open the disc in the given DVD-ROM drive. - </para></listitem> + Tries to open the disc in the given DVD-ROM drive. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlayVCD</emphasis></term> <listitem><para> -Tries to open the disc in the given CD-ROM drive. - </para></listitem> + Tries to open the disc in the given CD-ROM drive. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPreferences</emphasis></term> <listitem><para> -Open the preferences window. - </para></listitem> + Open the preferences window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetAspect</emphasis></term> <listitem><para> -Sets displayed image aspect. - </para></listitem> + Sets displayed image aspect. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetURL</emphasis></term> <listitem><para> -Displays the URL dialog window. - </para></listitem> + Displays the URL dialog window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSkinBrowser</emphasis></term> <listitem><para> -Open the skin browser window. - </para></listitem> + Open the skin browser window. + </para></listitem> </varlistentry> </variablelist> +</sect1> -</sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="skin-quality"> <title>Creating quality skins</title> @@ -1122,31 +1203,40 @@ </para> <itemizedlist> - <listitem><para>Each skin should come with a +<listitem><para> + Each skin should come with a <filename>README</filename> file that contains information about you, the author, copyright and license notices and anything else you wish to add. If you wish to have a changelog, this file is a - good place.</para></listitem> + good place. +</para></listitem> - <listitem><para>There should be a file <filename>VERSION</filename> +<listitem><para> + There should be a file <filename>VERSION</filename> with nothing more than the version number of the skin on a single - line (e.g. 1.0).</para></listitem> + line (e.g. 1.0). +</para></listitem> - <listitem><para>Horizontal and vertical controls (sliders like volume +<listitem><para> + Horizontal and vertical controls (sliders like volume or position) should have the center of the knob properly centered on the middle of the slider. It should be possible to move the knob to - both ends of the slider, but not past it.</para></listitem> + both ends of the slider, but not past it. +</para></listitem> - <listitem><para>Skin elements should have the right sizes declared +<listitem><para> + Skin elements should have the right sizes declared in the skin file. If this is not the case you can click outside of e.g. a button and still trigger it or click inside its area and not - trigger it.</para></listitem> + trigger it. +</para></listitem> - <listitem><para>The <filename>skin</filename> file should be +<listitem><para> + The <filename>skin</filename> file should be prettyprinted and not contain tabs. Prettyprinted means that the - numbers should line up neatly in columns.</para></listitem> + numbers should line up neatly in columns. +</para></listitem> </itemizedlist> </sect1> - </appendix>
--- a/DOCS/xml/en/tvinput.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/tvinput.xml Fri Dec 08 11:38:06 2006 +0000 @@ -12,6 +12,7 @@ of TV options and keyboard controls. </para> +<!-- ********** --> <sect2 id="tv-compilation"> <title>Compilation</title> @@ -22,196 +23,165 @@ autodetect kernel headers of v4l stuff and the existence of <filename>/dev/video*</filename> entries. If they exist, TV support will be built (see the output of <filename>./configure</filename>). - </para></step> +</para></step> <step><para> Make sure your tuner works with another TV software in Linux, for example <application>XawTV</application>. - </para></step> +</para></step> </procedure> </sect2> +<!-- ********** --> + <sect2 id="tv-tips"> <title>Usage tips</title> + <para> The full listing of the options is available on the manual page. Here are just a few tips: </para> + <itemizedlist> -<listitem> -<para> -Use the <option>channels</option> option. An example: -<screen>-tv channels=26-MTV1,23-TV2</screen> -Explanation: using this option, only the 26 and 23 channels will be usable, -and there will be a nice OSD text upon channel switching, displaying the -channel's name. Spaces in the channel name must be replaced by the -"_" character. -</para> -</listitem> - -<listitem> -<para> -Choose some sane image dimensions. The dimensions of the resulting image should -be divisible by 16. -</para> -</listitem> - -<listitem> -<para> -If you capture the video with the vertical resolution higher than half -of the full resolution (i.e. 288 for PAL or 240 for NTSC), then the -'frames' you get will really be interleaved pairs of fields. -Depending on what you want to do with the video you may leave it in -this form, destructively deinterlace, or break the pairs apart into -individual fields. -</para> -<para> -Otherwise you'll get a movie which is distorted during -fast-motion scenes and the bitrate controller will be probably even unable -to retain the specified bitrate as the interlacing artifacts produce high -amount of detail and thus consume lot of bandwidth. You can enable -deinterlacing with <option>-vf pp=DEINT_TYPE</option>. Usually -<option>pp=lb</option> does a good job, but it can be matter of personal -preference. See other deinterlacing algorithms in the manual and give it a try. -</para> -</listitem> - -<listitem> -<para> -Crop out the dead space. When you capture the video, the areas at the edges -are usually black or contain some noise. These again consume lots of -unnecessary bandwidth. More precisely it's not the black areas themselves -but the sharp transitions between the black and the brighter video image -which do but that's not important for now. Before you start capturing, -adjust the arguments of the <option>crop</option> option so that all the -crap at the margins is cropped out. Again, don't forget to keep the resulting -dimensions sane. -</para> -</listitem> - +<listitem><para> + Use the <option>channels</option> option. An example: + <screen>-tv channels=26-MTV1,23-TV2</screen> + Explanation: using this option, only the 26 and 23 channels will be usable, + and there will be a nice OSD text upon channel switching, displaying the + channel's name. Spaces in the channel name must be replaced by the + "_" character. +</para></listitem> +<listitem><para> + Choose some sane image dimensions. The dimensions of the resulting image + should be divisible by 16. +</para></listitem> <listitem> -<para> -Watch out for CPU load. It shouldn't cross the 90% boundary for most of the -time. If you have a large capture buffer, <application>MEncoder</application> -can survive an overload for few seconds but nothing more. It's better to -turn off the 3D OpenGL screensavers and similar stuff. -</para> -</listitem> - -<listitem> -<para> -Don't mess with the system clock. <application>MEncoder</application> uses the -system clock for doing A/V sync. If you adjust the system clock (especially -backwards in time), <application>MEncoder</application> gets confused and you -will lose frames. This is an important issue if you are hooked to a network -and run some time synchronization software like NTP. You have to turn NTP -off during the capture process if you want to capture reliably. -</para> + <para> + If you capture the video with the vertical resolution higher than half + of the full resolution (i.e. 288 for PAL or 240 for NTSC), then the + 'frames' you get will really be interleaved pairs of fields. + Depending on what you want to do with the video you may leave it in + this form, destructively deinterlace, or break the pairs apart into + individual fields. + </para> + <para> + Otherwise you'll get a movie which is distorted during + fast-motion scenes and the bitrate controller will be probably even unable + to retain the specified bitrate as the interlacing artifacts produce high + amount of detail and thus consume lot of bandwidth. You can enable + deinterlacing with <option>-vf pp=DEINT_TYPE</option>. + Usually <option>pp=lb</option> does a good job, but it can be matter of + personal preference. + See other deinterlacing algorithms in the manual and give it a try. + </para> </listitem> - -<listitem> -<para> -Don't change the <option>outfmt</option> unless you know what you are doing -or your card/driver really doesn't support the default (YV12 colorspace). -In the older versions of <application>MPlayer</application>/ -<application>MEncoder</application> it was necessary to specify the output -format. This issue should be fixed in the current releases and <option>outfmt</option> -isn't required anymore, and the default suits the most purposes. For example, -if you are capturing into DivX using -<systemitem class="library">libavcodec</systemitem> and specify -<option>outfmt=RGB24</option> in order to increase the quality of the captured -images, the captured image will be actually later converted back into YV12 so -the only thing you achieve is a massive waste of CPU power. -</para> -</listitem> - -<listitem> -<para> -To specify the I420 colorspace (<option>outfmt=i420</option>), you have to add an -option <option>-vc rawi420</option> due to a fourcc conflict with an Intel Indeo -video codec. -</para> -</listitem> - -<listitem> -<para> -There are several ways of capturing audio. You can grab the sound either using -your sound card via an external cable connection between video card and line-in, -or using the built-in ADC in the bt878 chip. In the latter case, you have to -load the <emphasis role="bold">btaudio</emphasis> driver. Read the -<filename>linux/Documentation/sound/btaudio</filename> file (in the kernel -tree, not <application>MPlayer</application>'s) for some instructions on using -this driver. -</para> -</listitem> - -<listitem> -<para> -If <application>MEncoder</application> cannot open the audio device, make -sure that it is really available. There can be some trouble with the sound -servers like aRts (KDE) or ESD (GNOME). If you have a full duplex sound card -(almost any decent card supports it today), and you are using KDE, try to -check the "full duplex" option in the sound server preference menu. -</para> -</listitem> +<listitem><para> + Crop out the dead space. When you capture the video, the areas at the edges + are usually black or contain some noise. These again consume lots of + unnecessary bandwidth. More precisely it's not the black areas themselves + but the sharp transitions between the black and the brighter video image + which do but that's not important for now. Before you start capturing, + adjust the arguments of the <option>crop</option> option so that all the + crap at the margins is cropped out. Again, don't forget to keep the resulting + dimensions sane. +</para></listitem> +<listitem><para> + Watch out for CPU load. It shouldn't cross the 90% boundary for most of the + time. If you have a large capture buffer, <application>MEncoder</application> + can survive an overload for few seconds but nothing more. It's better to + turn off the 3D OpenGL screensavers and similar stuff. +</para></listitem> +<listitem><para> + Don't mess with the system clock. <application>MEncoder</application> uses the + system clock for doing A/V sync. If you adjust the system clock (especially + backwards in time), <application>MEncoder</application> gets confused and you + will lose frames. This is an important issue if you are hooked to a network + and run some time synchronization software like NTP. You have to turn NTP + off during the capture process if you want to capture reliably. +</para></listitem> +<listitem><para> + Don't change the <option>outfmt</option> unless you know what you are doing + or your card/driver really doesn't support the default (YV12 colorspace). + In the older versions of <application>MPlayer</application>/ + <application>MEncoder</application> it was necessary to specify the output + format. This issue should be fixed in the current releases and + <option>outfmt</option> isn't required anymore, and the default suits the + most purposes. For example, if you are capturing into DivX using + <systemitem class="library">libavcodec</systemitem> and specify + <option>outfmt=RGB24</option> in order to increase the quality of the captured + images, the captured image will be actually later converted back into YV12 so + the only thing you achieve is a massive waste of CPU power. +</para></listitem> +<listitem><para> + To specify the I420 colorspace (<option>outfmt=i420</option>), you have to + add an option <option>-vc rawi420</option> due to a fourcc conflict with an + Intel Indeo video codec. +</para></listitem> +<listitem><para> + There are several ways of capturing audio. You can grab the sound either using + your sound card via an external cable connection between video card and + line-in, or using the built-in ADC in the bt878 chip. In the latter case, you + have to load the <emphasis role="bold">btaudio</emphasis> driver. Read the + <filename>linux/Documentation/sound/btaudio</filename> file (in the kernel + tree, not <application>MPlayer</application>'s) for some instructions on using + this driver. +</para></listitem> +<listitem><para> + If <application>MEncoder</application> cannot open the audio device, make + sure that it is really available. There can be some trouble with the sound + servers like aRts (KDE) or ESD (GNOME). If you have a full duplex sound card + (almost any decent card supports it today), and you are using KDE, try to + check the "full duplex" option in the sound server preference menu. +</para></listitem> </itemizedlist> </sect2> +<!-- ********** --> <sect2 id="tv-examples"> <title>Examples</title> -<informalexample> -<para> +<informalexample><para> Dummy output, to AAlib :) -<screen> -mplayer -tv driver=dummy:width=640:height=480 -vo aa tv://<!-- ---></screen> -</para> -</informalexample> +<screen>mplayer -tv driver=dummy:width=640:height=480 -vo aa tv://</screen> +</para></informalexample> -<informalexample> -<para> +<informalexample><para> Input from standard V4L: <screen> -mplayer -tv driver=v4l:width=640:height=480:outfmt=i420 -vc rawi420 -vo xv tv://<!-- ---></screen> -</para> -</informalexample> +mplayer -tv driver=v4l:width=640:height=480:outfmt=i420 -vc rawi420 -vo xv tv:// +</screen> +</para></informalexample> -<informalexample> -<para> +<informalexample><para> A more sophisticated example. This makes <application>MEncoder</application> capture the full PAL image, crop the margins, and deinterlace the picture using a linear blend algorithm. Audio is compressed with a constant bitrate of 64kbps, using LAME codec. This setup is suitable for capturing movies. <screen> - mencoder -tv driver=v4l:width=768:height=576 \ - -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=900 \ - -oac mp3lame -lameopts cbr:br=64 \ - -vf crop=720:544:24:16,pp=lb -o <replaceable>output.avi</replaceable> tv:// +mencoder -tv driver=v4l:width=768:height=576 -oac mp3lame -lameopts cbr:br=64\ + -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=900 \ + -vf crop=720:544:24:16,pp=lb -o <replaceable>output.avi</replaceable> tv:// </screen> -</para> -</informalexample> +</para></informalexample> -<informalexample> -<para> +<informalexample><para> This will additionally rescale the image to 384x288 and compresses the video with the bitrate of 350kbps in high quality mode. The vqmax option looses the quantizer and allows the video compressor to actually reach so low bitrate even at the expense of the quality. This can be used for capturing long TV series, where the video quality isn't so important. <screen> - mencoder -tv driver=v4l:width=768:height=576 \ - -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=350:vhq:vqmax=31:keyint=300 \ - -oac mp3lame -lameopts cbr:br=48 \ - -vf crop=720:540:24:18,pp=lb,scale=384:288 -sws 1 -o <replaceable>output.avi</replaceable> tv:// +mencoder -tv driver=v4l:width=768:height=576 \ + -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=350:vhq:vqmax=31:keyint=300 \ + -oac mp3lame -lameopts cbr:br=48 -sws 1 -o <replaceable>output.avi</replaceable>\ + -vf crop=720:540:24:18,pp=lb,scale=384:288 tv:// </screen> -It's also possible to specify smaller image dimensions in the <option>-tv</option> -option and omit the software scaling but this approach uses the maximum available -information and is a little more resistant to noise. The bt8x8 chips can do the -pixel averaging only in the horizontal direction due to a hardware limitation. -</para> -</informalexample> +It's also possible to specify smaller image dimensions in the +<option>-tv</option> option and omit the software scaling but this approach +uses the maximum available information and is a little more resistant to noise. +The bt8x8 chips can do the pixel averaging only in the horizontal direction due +to a hardware limitation. +</para></informalexample> </sect2> </sect1>
--- a/DOCS/xml/en/usage.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/usage.xml Fri Dec 08 11:38:06 2006 +0000 @@ -9,21 +9,18 @@ <para> <application>MPlayer</application> utilizes a complex playtree. It consists of global options written as first, for example - <screen>mplayer -vfm 5</screen> - and options written after filenames, that apply only to the given filename/URL/whatever, for example: - -<screen>mplayer -vfm 5 <replaceable>movie1.avi</replaceable> <replaceable>movie2.avi</replaceable> -vfm 4</screen> +<screen> +mplayer -vfm 5 <replaceable>movie1.avi</replaceable> <replaceable>movie2.avi</replaceable> -vfm 4 +</screen> </para> <para> You can group filenames/URLs together using <literal>{</literal> and <literal>}</literal>. It is useful with option <option>-loop</option>: - <screen>mplayer { 1.avi -loop 2 2.avi } -loop 3</screen> - The above command will play files in this order: 1, 1, 2, 1, 1, 2, 1, 1, 2. </para> @@ -105,6 +102,12 @@ </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="subosd"> <title>Subtitles and OSD</title> @@ -112,33 +115,35 @@ <application>MPlayer</application> can display subtitles along with movie files. Currently the following formats are supported: <itemizedlist> -<listitem><para>VOBsub</para></listitem> -<listitem><para>OGM</para></listitem> -<listitem><para>CC (closed caption)</para></listitem> -<listitem><para>MicroDVD</para></listitem> -<listitem><para>SubRip</para></listitem> -<listitem><para>SubViewer</para></listitem> -<listitem><para>Sami</para></listitem> -<listitem><para>VPlayer</para></listitem> -<listitem><para>RT</para></listitem> -<listitem><para>SSA</para></listitem> -<listitem><para>PJS (Phoenix Japanimation Society)</para></listitem> -<listitem><para>MPsub</para></listitem> -<listitem><para>AQTitle</para></listitem> -<listitem><para><ulink url="http://unicorn.us.com/jacosub/">JACOsub</ulink></para></listitem> + <listitem><para>VOBsub</para></listitem> + <listitem><para>OGM</para></listitem> + <listitem><para>CC (closed caption)</para></listitem> + <listitem><para>MicroDVD</para></listitem> + <listitem><para>SubRip</para></listitem> + <listitem><para>SubViewer</para></listitem> + <listitem><para>Sami</para></listitem> + <listitem><para>VPlayer</para></listitem> + <listitem><para>RT</para></listitem> + <listitem><para>SSA</para></listitem> + <listitem><para>PJS (Phoenix Japanimation Society)</para></listitem> + <listitem><para>MPsub</para></listitem> + <listitem><para>AQTitle</para></listitem> + <listitem><para> + <ulink url="http://unicorn.us.com/jacosub/">JACOsub</ulink> + </para></listitem> </itemizedlist> </para> <para> -<application>MPlayer</application> can dump the previously listed subtitle formats -(<emphasis role="bold">except the three first</emphasis>) into the following -destination formats, with the given options: +<application>MPlayer</application> can dump the previously listed subtitle +formats (<emphasis role="bold">except the three first</emphasis>) into the +following destination formats, with the given options: <itemizedlist> -<listitem><para>MPsub: <option>-dumpmpsub</option></para></listitem> -<listitem><para>SubRip: <option>-dumpsrtsub</option></para></listitem> -<listitem><para>MicroDVD: <option>-dumpmicrodvdsub</option></para></listitem> -<listitem><para>JACOsub: <option>-dumpjacosub</option></para></listitem> -<listitem><para>Sami: <option>-dumpsami</option></para></listitem> + <listitem><para>MPsub: <option>-dumpmpsub</option></para></listitem> + <listitem><para>SubRip: <option>-dumpsrtsub</option></para></listitem> + <listitem><para>MicroDVD: <option>-dumpmicrodvdsub</option></para></listitem> + <listitem><para>JACOsub: <option>-dumpjacosub</option></para></listitem> + <listitem><para>Sami: <option>-dumpsami</option></para></listitem> </itemizedlist> </para> @@ -154,9 +159,9 @@ <formalpara> <title>VOBsub subtitles</title> <para> -VOBsub subtitles consist of a big (some megabytes) <filename>.SUB</filename> file, -and optional <filename>.IDX</filename> and/or <filename>.IFO</filename> -files. If you have files like +VOBsub subtitles consist of a big (some megabytes) <filename>.SUB</filename> +file, and optional <filename>.IDX</filename> and/or <filename>.IFO</filename> +files. If you have files like <filename><replaceable>sample.sub</replaceable></filename>, <filename><replaceable>sample.ifo</replaceable></filename> (optional), <filename><replaceable>sample.idx</replaceable></filename> - you have to pass @@ -166,9 +171,9 @@ <option>-sid</option> for DVDs, you can choose between subtitle tracks (languages) with it. In case that <option>-vobsubid</option> is omitted, <application>MPlayer</application> will try to use the languages given by the -<option>-slang</option> option and fall back to the <systemitem>langidx</systemitem> -in the <filename>.IDX</filename> file to set the subtitle language. If it fails, -there will be no subtitles. +<option>-slang</option> option and fall back to the +<systemitem>langidx</systemitem> in the <filename>.IDX</filename> file to set +the subtitle language. If it fails, there will be no subtitles. </para> </formalpara> @@ -190,19 +195,19 @@ <listitem><simpara> Delays subtitles by <option><replaceable>sec</replaceable></option> seconds. Can be negative. The value is added to movie's time position counter. - </simpara></listitem> + </simpara></listitem> </varlistentry> <varlistentry> <term><option>-subfps <replaceable>RATE</replaceable></option></term> <listitem><simpara> Specify frame/sec rate of subtitle file (float number). - </simpara></listitem> + </simpara></listitem> </varlistentry> <varlistentry> <term><option>-subpos <replaceable>0-100</replaceable></option></term> <listitem><simpara> Specify the position of subtitles. - </simpara></listitem> + </simpara></listitem> </varlistentry> </variablelist> @@ -217,7 +222,10 @@ <application>MPlayer</application> can do this conversion for you: -<screen>mplayer -dumpmicrodvdsub -fps <replaceable>subtitles_fps</replaceable> -subfps <replaceable>avi_fps</replaceable> -sub <replaceable>subtitle_filename</replaceable> <replaceable>dummy.avi</replaceable></screen> +<screen> +mplayer -dumpmicrodvdsub -fps <replaceable>subtitles_fps</replaceable> -subfps <replaceable>avi_fps</replaceable> \ + -sub <replaceable>subtitle_filename</replaceable> <replaceable>dummy.avi</replaceable> +</screen> </para> <para> @@ -226,6 +234,12 @@ </sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="control"> <title>Control</title> @@ -236,6 +250,7 @@ control (using LIRC). See the man page for the complete list of keyboard controls. </para> +<!-- ********** --> <sect2 id="ctrl-cfg"> <title>Controls configuration</title> @@ -275,6 +290,7 @@ </example> </sect2> +<!-- ********** --> <sect2 id="lirc"> <title>Control from LIRC</title> @@ -339,9 +355,11 @@ </para> </sect2> +<!-- ********** --> <sect2 id="slave-mode"> <title>Slave mode</title> + <para> The slave mode allows you to build simple frontends to <application>MPlayer</application>. When run with the @@ -353,6 +371,10 @@ </sect2> </sect1> +<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="streaming"> <title>Streaming from network or pipes</title> @@ -382,25 +404,32 @@ <screen>wget <replaceable>ftp://micorsops.com/something.avi</replaceable> -O - | mplayer -cache 8192 -</screen> </para></note> +<!-- ********** --> + <sect2 id="streaming-save"> <title>Saving streamed content</title> + <para> - Once you succeed in making <application>MPlayer</application> play - your favorite internet stream, you can use the option - <option>-dumpstream</option> to save the stream into a file. - For example: +Once you succeed in making <application>MPlayer</application> play +your favorite internet stream, you can use the option +<option>-dumpstream</option> to save the stream into a file. +For example: <screen> - mplayer <replaceable>http://217.71.208.37:8006</replaceable> -dumpstream -dumpfile <replaceable>stream.asf</replaceable> +mplayer <replaceable>http://217.71.208.37:8006</replaceable> -dumpstream -dumpfile <replaceable>stream.asf</replaceable> </screen> - will save the content streamed from - <replaceable>http://217.71.208.37:8006</replaceable> into - <replaceable>stream.asf</replaceable>. - This works with all protocols supported by - <application>MPlayer</application>, like MMS, RSTP, and so forth. +will save the content streamed from +<replaceable>http://217.71.208.37:8006</replaceable> into +<replaceable>stream.asf</replaceable>. +This works with all protocols supported by +<application>MPlayer</application>, like MMS, RSTP, and so forth. </para> </sect2> +</sect1> -</sect1> +<!-- ********** --> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="mpst" xreflabel="Remote streams"> <title>Remote streams</title> @@ -415,8 +444,11 @@ require an insane amount of bandwidth. </para> +<!-- ********** --> + <sect2 id="compile_mpst_server"> <title>Compiling the server</title> + <para> After having compiled <application>MPlayer</application> go to the <filename>TOOLS/netstream</filename> directory and enter @@ -427,8 +459,11 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="use_mpst"> <title>Using remote streams</title> + <para> First you have to start the server on the computer you intend to remotely access. Currently the server is very basic and does not have any commands @@ -442,8 +477,8 @@ mplayer -cache 5000 <replaceable>mpst://servername//usr/local/movies/lol.avi</replaceable> </screen> Note that paths which aren't starting with a / will be relative to -the directory where the server is running. The <option>-cache</option> option is not -needed but highly recommended. +the directory where the server is running. The <option>-cache</option> option +is not needed but highly recommended. </para> <para> @@ -451,10 +486,12 @@ about the numerous exploits which are possible through this. Instead send some (good) patch to make it better or start writing your own server. </para> +</sect2> +</sect1> -</sect2> -</sect1> +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <sect1 id="edl" xreflabel="Edit Decision Lists (EDL)"> <title>Edit Decision Lists (EDL)</title> @@ -477,8 +514,11 @@ indicates what to do (skip/mute) and when to do it (using pts in seconds). </para> +<!-- ********** --> + <sect2 id="edl_using"> <title>Using an EDL file</title> + <para> Include the <option>-edl <filename></option> flag when you run <application>MPlayer</application>, with the name of the EDL file you @@ -486,13 +526,14 @@ </para> </sect2> +<!-- ********** --> + <sect2 id="edl_making"> <title>Making an EDL file</title> + <para> The current EDL file format is: -<programlisting> -[begin second] [end second] [action] -</programlisting> +<programlisting>[begin second] [end second] [action]</programlisting> Where the seconds are floating-point numbers and the action is either <literal>0</literal> for skip or <literal>1</literal> for mute. Example: <programlisting> @@ -507,15 +548,18 @@ </para> <para> -To create an EDL file to work from, use the <option>-edlout <filename></option> -flag. During playback, just hit <keycap>i</keycap> to mark the beginning and -end of a skip block. A corresponding entry will be written to the file for -that time. You can then go back and fine-tune the generated EDL file as well as +To create an EDL file to work from, use the <option>-edlout +<filename></option> flag. During playback, just hit <keycap>i</keycap> to +mark the beginning and end of a skip block. +A corresponding entry will be written to the file for that time. +You can then go back and fine-tune the generated EDL file as well as change the default operation which is to skip the block described by each line. </para> </sect2> +</sect1> -</sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <sect1 id="advaudio" xreflabel="Advanced Audio"> @@ -526,23 +570,20 @@ <sect3 id="advaudio-surround-DVD"> <title>DVDs</title> + <para> Most DVDs and many other files include surround sound. <application>MPlayer</application> supports surround playback but does not enable it by default because stereo equipment is by far more common. To play a file that has more than two channels of audio use <option>-channels</option>. For example, to play a DVD with 5.1 audio: - <screen>mplayer dvd://1 -channels 6</screen> - Note that despite the name "5.1" there are actually six discrete channels. If you have surround sound equipment it is safe to put the <option>channels</option> option in your <application>MPlayer</application> configuration file <filename>~/.mplayer/config</filename>. For example, to make quadraphonic playback the default, add this line: - <programlisting>channels=4</programlisting> - <application>MPlayer</application> will then output audio in four channels when all four channels are available. </para> @@ -555,14 +596,11 @@ <para> <application>MPlayer</application> does not duplicate any channels by default, and neither do most audio drivers. If you want to do that manually: - <screen>mplayer <replaceable>filename</replaceable> -af channels=2:2:0:1:0:0</screen> - See the section on <link linkend="advaudio-channels-copying">channel copying</link> for an explanation. </para> - </sect3> @@ -586,13 +624,13 @@ <itemizedlist> <title>To enable passthrough on the command line:</title> <listitem><para> -For AC3 only, use <option>-ac hwac3</option> + For AC3 only, use <option>-ac hwac3</option> </para></listitem> <listitem><para> -For DTS only, use <option>-ac hwdts</option> + For DTS only, use <option>-ac hwdts</option> </para></listitem> <listitem><para> -For both AC3 and DTS, use <option>-afm hwac3</option> + For both AC3 and DTS, use <option>-afm hwac3</option> </para></listitem> </itemizedlist> @@ -600,13 +638,13 @@ <title>To enable passthrough in the <application>MPlayer</application> configuration file: </title> <listitem><para> -For AC3 only, use <option>ac=hwac3,</option> + For AC3 only, use <option>ac=hwac3,</option> </para></listitem> <listitem><para> -For DTS only, use <option>ac=hwdts,</option> + For DTS only, use <option>ac=hwdts,</option> </para></listitem> <listitem><para> -For both AC3 and DTS, use <option>afm=hwac3</option> + For both AC3 and DTS, use <option>afm=hwac3</option> </para></listitem> </itemizedlist> @@ -618,8 +656,8 @@ does not need a comma; <application>MPlayer</application> will fall back anyway when an audio family is specified. </para> +</sect3> -</sect3> <sect3 id="hwmpa-surround-passthrough"> <title>MPEG audio Passthrough</title> @@ -639,12 +677,14 @@ </para> </sect3> + <sect3 id="advaudio-surround-matrix"> <title>Matrix-encoded audio</title> <para> <emphasis>***TODO***</emphasis> </para> + <para> This section has yet to be written and cannot be completed until somebody provides sample files for us to test. If you have any matrix-encoded audio @@ -653,6 +693,7 @@ <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-docs">MPlayer-DOCS</ulink> mailing list. Put "[matrix-encoded audio]" in the subject line. </para> + <para> If no files or further information are forthcoming this section will be dropped. </para> @@ -661,14 +702,13 @@ Good links: <itemizedlist> <listitem><para> -<ulink url="http://electronics.howstuffworks.com/surround-sound5.htm">http://electronics.howstuffworks.com/surround-sound5.htm</ulink> + <ulink url="http://electronics.howstuffworks.com/surround-sound5.htm">http://electronics.howstuffworks.com/surround-sound5.htm</ulink> </para></listitem> <listitem><para> -<ulink url="http://www.extremetech.com/article2/0,1697,1016875,00.asp">http://www.extremetech.com/article2/0,1697,1016875,00.asp</ulink> + <ulink url="http://www.extremetech.com/article2/0,1697,1016875,00.asp">http://www.extremetech.com/article2/0,1697,1016875,00.asp</ulink> </para></listitem> </itemizedlist> </para> - </sect3> @@ -695,9 +735,7 @@ <para> To play a DVD with HRTF: - <screen>mplayer dvd://1 -channels 6 -af hrtf</screen> - </para> <para> @@ -705,11 +743,10 @@ <option>hrtf</option> requires 48 kHz audio. DVD audio is already 48 kHz, but if you have a file with a different sampling rate that you want to play using <option>hrtf</option> you must resample it: - -<screen>mplayer <replaceable>filename</replaceable> -channels 6 -af resample=48000,hrtf</screen> - +<screen> +mplayer <replaceable>filename</replaceable> -channels 6 -af resample=48000,hrtf +</screen> </para> - </sect3> @@ -721,11 +758,10 @@ settings with a mixer program such as <application>alsamixer</application>; audio outputs are often muted and set to zero volume by default. </para> - </sect3> - </sect2> +<!-- ********** --> <sect2 id="advaudio-channels"> <title>Channel manipulation</title> @@ -740,50 +776,49 @@ <orderedlist spacing="compact"> <title>mono</title> -<listitem override="0"><simpara>center</simpara></listitem> + <listitem override="0"><simpara>center</simpara></listitem> </orderedlist> <orderedlist spacing="compact"> <title>stereo</title> -<listitem override="0"><simpara>left</simpara></listitem> -<listitem><simpara>right</simpara></listitem> + <listitem override="0"><simpara>left</simpara></listitem> + <listitem><simpara>right</simpara></listitem> </orderedlist> <orderedlist spacing="compact"> <title>quadraphonic</title> -<listitem override="0"><simpara>left front</simpara></listitem> -<listitem><simpara>right front</simpara></listitem> -<listitem><simpara>left rear</simpara></listitem> -<listitem><simpara>right rear</simpara></listitem> + <listitem override="0"><simpara>left front</simpara></listitem> + <listitem><simpara>right front</simpara></listitem> + <listitem><simpara>left rear</simpara></listitem> + <listitem><simpara>right rear</simpara></listitem> </orderedlist> <orderedlist spacing="compact"> <title>surround 4.0</title> -<listitem override="0"><simpara>left front</simpara></listitem> -<listitem><simpara>right front</simpara></listitem> -<listitem><simpara>center rear</simpara></listitem> -<listitem><simpara>center front</simpara></listitem> + <listitem override="0"><simpara>left front</simpara></listitem> + <listitem><simpara>right front</simpara></listitem> + <listitem><simpara>center rear</simpara></listitem> + <listitem><simpara>center front</simpara></listitem> </orderedlist> <orderedlist spacing="compact"> <title>surround 5.0</title> -<listitem override="0"><simpara>left front</simpara></listitem> -<listitem><simpara>right front</simpara></listitem> -<listitem><simpara>left rear</simpara></listitem> -<listitem><simpara>right rear</simpara></listitem> -<listitem><simpara>center front</simpara></listitem> + <listitem override="0"><simpara>left front</simpara></listitem> + <listitem><simpara>right front</simpara></listitem> + <listitem><simpara>left rear</simpara></listitem> + <listitem><simpara>right rear</simpara></listitem> + <listitem><simpara>center front</simpara></listitem> </orderedlist> <orderedlist spacing="compact"> <title>surround 5.1</title> -<listitem override="0"><simpara>left front</simpara></listitem> -<listitem><simpara>right front</simpara></listitem> -<listitem><simpara>left rear</simpara></listitem> -<listitem><simpara>right rear</simpara></listitem> -<listitem><simpara>center front</simpara></listitem> -<listitem><simpara>subwoofer</simpara></listitem> + <listitem override="0"><simpara>left front</simpara></listitem> + <listitem><simpara>right front</simpara></listitem> + <listitem><simpara>left rear</simpara></listitem> + <listitem><simpara>right rear</simpara></listitem> + <listitem><simpara>center front</simpara></listitem> + <listitem><simpara>subwoofer</simpara></listitem> </orderedlist> - </para> <para> @@ -800,7 +835,6 @@ channels and is useful for controlling the number of channels sent to the sound card. See the following sections for more information on channel manipulation. </para> - </sect3> @@ -814,9 +848,7 @@ actually encoded as stereo with one channel silent. The easiest and most foolproof way to make both speakers output the same audio is the <option>extrastereo</option> filter: - <screen>mplayer <replaceable>filename</replaceable> -af extrastereo=0</screen> - </para> <para> @@ -826,11 +858,10 @@ depending on which channel to keep. If you really need to maintain the volume, it may be easier to experiment with the <option>volume</option> filter and find the right value. For example: - -<screen>mplayer <replaceable>filename</replaceable> -af extrastereo=0,volume=5</screen> - +<screen> +mplayer <replaceable>filename</replaceable> -af extrastereo=0,volume=5 +</screen> </para> - </sect3> @@ -844,55 +875,53 @@ <orderedlist spacing="compact"> <listitem><para> -Decide how many output channels you need. This is the first suboption. + Decide how many output channels you need. This is the first suboption. </para></listitem> <listitem><para> -Count how many channel moves you will do. This is the second suboption. Each -channel can be moved to several different channels at the same time, but keep in -mind that when a channel is moved (even if to only one destination) the source -channel will be empty unless another channel is moved into it. To copy a -channel, keeping the source the same, simply move the channel into both the -destination and the source. For example: -<programlisting> + Count how many channel moves you will do. This is the second suboption. Each + channel can be moved to several different channels at the same time, but keep + in mind that when a channel is moved (even if to only one destination) the + source channel will be empty unless another channel is moved into it. To copy + a channel, keeping the source the same, simply move the channel into both the + destination and the source. For example: + <programlisting> channel 2 --> channel 3 -channel 2 --> channel 2 -</programlisting> +channel 2 --> channel 2<!-- + --></programlisting> </para></listitem> <listitem><para> -Write out the channel copies as pairs of suboptions. Note that the first channel -is 0, the second is 1, etc. The order of these suboptions does not matter as -long as they are properly grouped into + Write out the channel copies as pairs of suboptions. Note that the first + channel is 0, the second is 1, etc. The order of these suboptions does not + matter as long as they are properly grouped into <replaceable>source:destination</replaceable> pairs. </para></listitem> </orderedlist> - </para> - <bridgehead>Example: one channel in two speakers</bridgehead> - <para> Here is an example of another way to play one channel in both speakers. Suppose for this example that the left channel should be played and the right channel discarded. Following the steps above: <orderedlist> <listitem><para> -In order to provide an output channel for each of the two speakers, the first -suboption must be "2". + In order to provide an output channel for each of the two speakers, the first + suboption must be "2". </para></listitem> <listitem><para> -The left channel needs to be moved to the right channel, and also must be moved -to itself so it won't be empty. This is a total of two moves, making the second -suboption "2" as well. + The left channel needs to be moved to the right channel, and also must be + moved to itself so it won't be empty. This is a total of two moves, making + the second suboption "2" as well. </para></listitem> <listitem><para> -To move the left channel (channel 0) into the right channel (channel 1), the -suboption pair is "0:1", "0:0" moves the left channel onto itself. + To move the left channel (channel 0) into the right channel (channel 1), the + suboption pair is "0:1", "0:0" moves the left channel onto itself. </para></listitem> </orderedlist> Putting that all together gives: - -<screen>mplayer <replaceable>filename</replaceable> -af channels=2:2:0:1:0:0</screen> +<screen> +mplayer <replaceable>filename</replaceable> -af channels=2:2:0:1:0:0 +</screen> </para> <para> @@ -903,13 +932,10 @@ </para> <bridgehead>Example: left channel in two speakers shortcut</bridgehead> - <para> There is actually a much easier way to use the <option>channels</option> filter for playing the left channel in both speakers: - <screen>mplayer <replaceable>filename</replaceable> -af channels=1</screen> - The second channel is discarded and, with no further suboptions, the single remaining channel is left alone. Sound card drivers automatically play single-channel audio in both speakers. This only works when the desired channel @@ -922,24 +948,24 @@ on the rear speakers of a quadraphonic setup. <orderedlist> <listitem><para> -There should be four output channels. The first suboption is "4". + There should be four output channels. The first suboption is "4". </para></listitem> <listitem><para> -Each of the two front channels needs to be moved to the corresponding rear -channel and also to itself. This is four moves, so the second suboption is "4". + Each of the two front channels needs to be moved to the corresponding rear + channel and also to itself. This is four moves, so the second suboption is "4". </para></listitem> <listitem><para> -The left front (channel 0) needs to moved to the left rear (channel 2): "0:2". -The left front also needs to be moved to itself: "0:0". The right front (channel -1) is moved to the right rear (channel 3): "1:3", and also to itself: "1:1". + The left front (channel 0) needs to moved to the left rear (channel 2): + "0:2". The left front also needs to be moved to itself: "0:0". The right + front (channel 1) is moved to the right rear (channel 3): "1:3", and also to + itself: "1:1". </para></listitem> </orderedlist> Combine all the suboptions to get: - -<screen>mplayer <replaceable>filename</replaceable> -af channels=4:4:0:2:0:0:1:3:1:1</screen> - +<screen> +mplayer <replaceable>filename</replaceable> -af channels=4:4:0:2:0:0:1:3:1:1 +</screen> </para> - </sect3> @@ -952,73 +978,69 @@ more. Unfortunately, the suboptions are much more complicated. <orderedlist> <listitem><para> -Decide how many channels to work with. You may need to specify this with -<option>-channels</option> and/or <option>-af channels</option>. Later examples -will show when to use which. -</para></listitem> -<listitem><para> -Decide how many channels to feed into <option>pan</option> (further decoded -channels are discarded). This is the first suboption, and it also controls how -many channels to employ for output. + Decide how many channels to work with. You may need to specify this with + <option>-channels</option> and/or <option>-af channels</option>. + Later examples will show when to use which. </para></listitem> <listitem><para> -The remaining suboptions specify how much of each channel gets mixed into each -other channel. This is the complicated part. To break the task down, split the -suboptions into several sets, one set for each output channel. Each suboption -within a set corresponds to an input channel. The number you specify will be the -percentage of the input channel that gets mixed into the output channel. -</para> -<para> -<option>pan</option> accepts values from 0 to 512, yielding 0% to 51200% of the -original volume. Be careful when using values greater than 1. Not only can this -give you very high volume, but if you exceed the sample range of your sound card -you may hear painful pops and clicks. If you want you can follow -<option>pan</option> with <option>,volume</option> to enable clipping, but it is -best to keep the values of <option>pan</option> low enough that clipping is not -necessary. + Decide how many channels to feed into <option>pan</option> (further decoded + channels are discarded). This is the first suboption, and it also controls how + many channels to employ for output. </para></listitem> +<listitem> + <para> + The remaining suboptions specify how much of each channel gets mixed into each + other channel. This is the complicated part. To break the task down, split the + suboptions into several sets, one set for each output channel. Each suboption + within a set corresponds to an input channel. The number you specify will be + the percentage of the input channel that gets mixed into the output channel. + </para> + <para> + <option>pan</option> accepts values from 0 to 512, yielding 0% to 51200% of + the original volume. Be careful when using values greater than 1. Not only + can this give you very high volume, but if you exceed the sample range of + your sound card you may hear painful pops and clicks. If you want you can + follow <option>pan</option> with <option>,volume</option> to enable clipping, + but it is best to keep the values of <option>pan</option> low enough that + clipping is not necessary. + </para> +</listitem> </orderedlist> </para> <bridgehead>Example: one channel in two speakers</bridgehead> - <para> Here is yet another example for playing the left channel in two speakers. Follow the steps above: <orderedlist> <listitem><para> -<option>pan</option> should output two channels, so the first -suboption is "2". + <option>pan</option> should output two channels, so the first + suboption is "2". </para></listitem> <listitem><para> -Since we have two input channels, there will be two sets of suboptions. -Since there are also two output channels, -there will be two suboptions per set. -The left channel from the file should go with full volume to -the new left and the right channels. -Thus the first set of suboptions is "1:1". -The right channel should be discarded, so the second would be "0:0". -Any 0 values at the end can be left out, but for ease of -understanding we will keep them. + Since we have two input channels, there will be two sets of suboptions. + Since there are also two output channels, + there will be two suboptions per set. + The left channel from the file should go with full volume to + the new left and the right channels. + Thus the first set of suboptions is "1:1". + The right channel should be discarded, so the second would be "0:0". + Any 0 values at the end can be left out, but for ease of + understanding we will keep them. </para></listitem> </orderedlist> Putting those options together gives: - <screen>mplayer <replaceable>filename</replaceable> -af pan=2:1:1:0:0</screen> - If the right channel is desired instead of the left, the suboptions to <option>pan</option> will be "2:0:0:1:1". </para> <bridgehead>Example: left channel in two speakers shortcut</bridgehead> - <para> As with <option>channels</option>, there is a shortcut that only works with the left channel: - <screen>mplayer <replaceable>filename</replaceable> -af pan=1:1</screen> - Since <option>pan</option> has only one channel of input (the other channel is discarded), there is only one set with one suboption, which specifies that the only channel gets 100% of itself. @@ -1030,40 +1052,39 @@ downmixing. Here is a way to downmix PCM using <option>pan</option>: <orderedlist> <listitem><para> -The number of output channels is 2, so the first suboption is "2". + The number of output channels is 2, so the first suboption is "2". </para></listitem> <listitem><para> -With six input channels there will be six sets of options. Fortunately, -since we only care about the output of the first two channels, we only need to -make two sets; the remaining four sets can be omitted. Beware that not all -multichannel audio files have the same channel order! This example -demonstrates downmixing a file with the same channels as AC3 5.1: -<programlisting> + With six input channels there will be six sets of options. Fortunately, + since we only care about the output of the first two channels, we only need to + make two sets; the remaining four sets can be omitted. Beware that not all + multichannel audio files have the same channel order! This example + demonstrates downmixing a file with the same channels as AC3 5.1: + <programlisting> 0 - front left 1 - front right 2 - rear left 3 - rear right 4 - center front -5 - subwoofer -</programlisting> -The first set of suboptions lists the percentages of the original volume, in -order, which each output channel should receive from the -front left channel: "1:0". -The front right channel should go into the right output: "0:1". -The same for the rear channels: "1:0" and "0:1". -The center channel goes into both output channels with half volume: -"0.5:0.5", and the subwoofer goes into both with full volume: "1:1". +5 - subwoofer<!-- + --></programlisting> + The first set of suboptions lists the percentages of the original volume, in + order, which each output channel should receive from the + front left channel: "1:0". + The front right channel should go into the right output: "0:1". + The same for the rear channels: "1:0" and "0:1". + The center channel goes into both output channels with half volume: + "0.5:0.5", and the subwoofer goes into both with full volume: "1:1". </para></listitem> </orderedlist> Put all that together, for: - -<screen>mplayer <replaceable>6-channel.wav</replaceable> -af pan=2:1:0:0:1:1:0:0:1:0.5:0.5:1:1</screen> - +<screen> +mplayer <replaceable>6-channel.wav</replaceable> -af pan=2:1:0:0:1:1:0:0:1:0.5:0.5:1:1 +</screen> The percentages listed above are only a rough example. Feel free to tweak them. </para> <bridgehead>Example: Playing 5.1 audio on big speakers without a subwoofer</bridgehead> - <para> If you have a huge pair of front speakers you may not want to waste any money on buying a subwoofer for a complete 5.1 sound system. If you use @@ -1071,56 +1092,54 @@ the subwoofer channel is simply discarded. If you want to distribute the subwoofer channel yourself you need to downmix manually with <option>pan</option>: - <orderedlist> <listitem><para> -Since <option>pan</option> needs to examine all six channels, specify -<option>-channels 6</option> so liba52 decodes them all. + Since <option>pan</option> needs to examine all six channels, specify + <option>-channels 6</option> so liba52 decodes them all. </para></listitem> <listitem><para> -<option>pan</option> outputs to only five channels, the first suboption is 5. + <option>pan</option> outputs to only five channels, the first suboption is 5. </para></listitem> <listitem><para> -Six input channels and five output channels means six sets of five suboptions. + Six input channels and five output channels means six sets of five suboptions. <itemizedlist spacing="compact"> <listitem><simpara> - The left front channel only replicates onto itself: - "1:0:0:0:0" + The left front channel only replicates onto itself: + "1:0:0:0:0" </simpara></listitem> <listitem><simpara> - Same for the right front channel: - "0:1:0:0:0" + Same for the right front channel: + "0:1:0:0:0" </simpara></listitem> <listitem><simpara> - Same for the left rear channel: - "0:0:1:0:0" + Same for the left rear channel: + "0:0:1:0:0" </simpara></listitem> <listitem><simpara> - And also the same for the right rear channel: - "0:0:0:1:0" + And also the same for the right rear channel: + "0:0:0:1:0" </simpara></listitem> <listitem><simpara> - Center front, too: - "0:0:0:0:1" + Center front, too: + "0:0:0:0:1" </simpara></listitem> <listitem><simpara> - And now we have to decide what to do with the subwoofer, - e.g. half into front right and front left: - "0.5:0.5:0:0:0" + And now we have to decide what to do with the subwoofer, + e.g. half into front right and front left: + "0.5:0.5:0:0:0" </simpara></listitem> </itemizedlist> </para></listitem> </orderedlist> Combine all those options to get: - -<screen>mplayer <replaceable>dvd://1</replaceable> -channels 6 -af pan=5:1:0:0:0:0:0:1:0:0:0:0:0:1:0:0:0:0:0:1:0:0:0:0:0:1:0.5:0.5:0:0:0</screen> - +<screen> +mplayer <replaceable>dvd://1</replaceable> -channels 6 -af pan=5:1:0:0:0:0:0:1:0:0:0:0:0:1:0:0:0:0:0:1:0:0:0:0:0:1:0.5:0.5:0:0:0 +</screen> </para> - </sect3> - </sect2> +<!-- ********** --> <sect2 id="advaudio-volume"> <title>Software Volume adjustment</title> @@ -1134,11 +1153,10 @@ <keycap>0</keycap>) to reach much higher volume levels. Note that this does not bypass your sound card's mixer; <application>MPlayer</application> only amplifies the signal before sending it to your sound card. - The following example is a good start: - -<screen>mplayer <replaceable>quiet-file</replaceable> -softvol -softvol-max 300</screen> - +<screen> +mplayer <replaceable>quiet-file</replaceable> -softvol -softvol-max 300 +</screen> The <option>-softvol-max</option> option specifies the maximum allowable output volume as a percentage of the original volume. For example, <option>-softvol-max 200</option> would allow the @@ -1156,20 +1174,15 @@ The <option>-softvol</option> option works by controlling the <option>volume</option> audio filter. If you want to play a file at a certain volume from the beginning you can specify <option>volume</option> manually: - <screen>mplayer <replaceable>quiet-file</replaceable> -af volume=10</screen> - This will play the file with a ten decibel gain. Be careful when using the <option>volume</option> filter - you could easily hurt your ears if you use too high a value. Start low and work your way up gradually until you get a feel for how much adjustment is required. Also, if you specify excessively high -values, <option>volume</option> may need to clip the signal to avoid sending your -sound card data that is outside the allowable range; this will result in +values, <option>volume</option> may need to clip the signal to avoid sending +your sound card data that is outside the allowable range; this will result in distorted audio. </para> - </sect2> - </sect1> - </chapter>
--- a/DOCS/xml/en/video.xml Fri Dec 08 09:50:12 2006 +0000 +++ b/DOCS/xml/en/video.xml Fri Dec 08 11:38:06 2006 +0000 @@ -58,12 +58,12 @@ <informaltable frame="none"> <tgroup cols="2"> <tbody> -<row><entry>1 MB</entry><entry>0x100000</entry></row> -<row><entry>2 MB</entry><entry>0x200000</entry></row> -<row><entry>4 MB</entry><entry>0x400000</entry></row> -<row><entry>8 MB</entry><entry>0x800000</entry></row> -<row><entry>16 MB</entry><entry>0x1000000</entry></row> -<row><entry>32 MB</entry><entry>0x2000000</entry></row> + <row><entry>1 MB</entry><entry>0x100000</entry></row> + <row><entry>2 MB</entry><entry>0x200000</entry></row> + <row><entry>4 MB</entry><entry>0x400000</entry></row> + <row><entry>8 MB</entry><entry>0x800000</entry></row> + <row><entry>16 MB</entry><entry>0x1000000</entry></row> + <row><entry>32 MB</entry><entry>0x2000000</entry></row> </tbody> </tgroup> </informaltable> @@ -119,8 +119,8 @@ in <filename>/var/log/XFree86.0.log</filename> <note><para> This loads only the XFree86's extension. In a good install, this is - always loaded, and doesn't mean that the <emphasis role="bold">card's</emphasis> - XVideo support is loaded! + always loaded, and doesn't mean that the + <emphasis role="bold">card's</emphasis> XVideo support is loaded! </para></note> </para></listitem> <listitem><para> @@ -159,9 +159,7 @@ And finally, check if <application>MPlayer</application> was compiled with 'xv' support. Do a <command>mplayer -vo help | grep xv </command>. If 'xv' support was built a line similar to this should appear: - <screen> - xv X11/Xv<!-- - --></screen> + <screen> xv X11/Xv</screen> </para></listitem> </orderedlist> </para> @@ -205,13 +203,11 @@ will also help). </para> -<note> -<para> +<note><para> It's currently unclear which Savage models lack YV12 support, and convert by driver (slow). If you suspect your card, get a newer driver, or ask politely on the MPlayer-users mailing list for an MMX/3DNow! enabled driver. -</para> -</note> +</para></note> </sect3> @@ -254,8 +250,9 @@ <para> Radeon VE - if you need X, use XFree86 4.2.0 or greater for this card. No TV out support. Of course with <application>MPlayer</application> you can -happily get <emphasis role="bold">accelerated</emphasis> display, with or without -<emphasis role="bold">TV output</emphasis>, and no libraries or X are needed. +happily get <emphasis role="bold">accelerated</emphasis> display, with or +without <emphasis role="bold">TV output</emphasis>, and no libraries or X are +needed. Read the <link linkend="vidix">VIDIX</link> section. </para> </sect3> @@ -275,8 +272,8 @@ XFree86 4.3.0 includes Xv support, yet Bohdan Horst sent a small <ulink url="http://www.mplayerhq.hu/MPlayer/contrib/NeoMagic-driver/neo_driver.patch">patch</ulink> against the XFree86 sources that speeds up framebuffer operations (so XVideo) -up to four times. The patch has been included in XFree86 CVS and should be in the -next release after 4.3.0. +up to four times. The patch has been included in XFree86 CVS and should be in +the next release after 4.3.0. </para> <para> @@ -381,7 +378,8 @@ <programlisting>(II) Loading extension XFree86-DGA</programlisting> -See, XFree86 4.0.x or greater is <emphasis role="bold">highly recommended</emphasis>! +See, XFree86 4.0.x or greater is +<emphasis role="bold">highly recommended</emphasis>! <application>MPlayer</application>'s DGA driver is autodetected by <filename>./configure</filename>, or you can force it with <option>--enable-dga</option>. @@ -413,9 +411,9 @@ <title>Security risk</title> <para> This is a <emphasis role="bold">big</emphasis> security risk! -<emphasis role="bold">Never</emphasis> do this on a server or on a computer that can be -accessed by other people because they can gain root privileges through SUID root -<application>MPlayer</application>. +<emphasis role="bold">Never</emphasis> do this on a server or on a computer +that can be accessed by other people because they can gain root privileges +through SUID root <application>MPlayer</application>. </para> </caution> @@ -605,7 +603,6 @@ </itemizedlist> </sect2> -<!--</sect1>--> <!-- ********** --> @@ -655,14 +652,12 @@ </para> </formalpara> -<note> -<para> +<note><para> Be sure not to use the <option>-fs</option> switch, since it toggles the usage of the software scaler, and it's slow. If you really need it, use the <option>-sws 4</option> option which will produce bad quality, but is somewhat faster. -</para> -</note> +</para></note> <formalpara> <title>EGA (4BPP) SUPPORT</title> @@ -790,8 +785,8 @@ <option>-bpp</option> option, then that. </para></listitem> <listitem><para> - <option>-zoom</option> option isn't supported (use <option>-vf scale</option>). - You can't use 8bpp (or less) modes. + <option>-zoom</option> option isn't supported + (use <option>-vf scale</option>). You can't use 8bpp (or less) modes. </para></listitem> <listitem><para> You possibly want to turn the cursor off: @@ -807,13 +802,11 @@ </para></listitem> </itemizedlist> -<note> -<para> +<note><para> FBdev video mode changing <emphasis>does not work</emphasis> with the VESA framebuffer, and don't ask for it, since it's not an <application>MPlayer</application> limitation. -</para> -</note> +</para></note> </sect2> <!-- ********** --> @@ -828,12 +821,10 @@ framebuffer console and under X. </para> -<warning> -<para> +<warning><para> This is Linux only! On non-Linux (tested on FreeBSD) systems, you can use <link linkend="vidix">VIDIX</link> instead! -</para> -</warning> +</para></warning> <procedure> <title>Installation:</title> @@ -948,7 +939,7 @@ <!-- ********** --> <sect2 id="aalib"> -<title>AAlib - text mode displaying</title> +<title>AAlib – text mode displaying</title> <para> AAlib is a library for displaying graphics in text mode, using powerful @@ -1049,15 +1040,13 @@ </varlistentry> </variablelist> -<note> -<para> +<note><para> The rendering is very CPU intensive, especially when using AA-on-X (using aalib on X), and it's least CPU intensive on standard, non-framebuffer console. Use SVGATextMode to set up a big textmode, then enjoy! (secondary head Hercules cards rock :)) (but IMHO you can use <option>-vf 1bpp</option> option to get graphics on hgafb:) -</para> -</note> +</para></note> <para> Use the <option>-framedrop</option> option if your computer isn't fast @@ -1078,7 +1067,9 @@ <!-- ********** --> <sect2 id="caca"> -<title><systemitem class="library">libcaca</systemitem> - Color ASCII Art library</title> +<title> +<systemitem class="library">libcaca</systemitem> – Color ASCII Art library +</title> <para> The <ulink url="http://sam.zoy.org/projects/libcaca/"><systemitem class="library">libcaca</systemitem></ulink> @@ -1141,7 +1132,8 @@ </informaltable> <variablelist> -<title><systemitem class="library">libcaca</systemitem> will also look for certain environment variables:</title> +<title><systemitem class="library">libcaca</systemitem> will also look for + certain environment variables:</title> <varlistentry> <term><option>CACA_DRIVER</option></term> <listitem><simpara> @@ -1255,12 +1247,10 @@ </simpara></listitem> </itemizedlist> -<important> -<para> +<important><para> Don't use this driver with <emphasis role="bold">GCC 2.96</emphasis>! It won't work! -</para> -</important> +</para></important> <variablelist> <title>COMMAND LINE OPTIONS AVAILABLE FOR VESA</title> @@ -1296,8 +1286,9 @@ be activated anyway and you will need restart your computer. </simpara></listitem> <listitem><simpara> - Often after terminating VESA driver you get <emphasis role="bold">black</emphasis> - screen. To return your screen to original state - simply switch to other console + Often after terminating VESA driver you get + <emphasis role="bold">black</emphasis> screen. To return your screen to + original state - simply switch to other console (by pressing <keycap>Alt</keycap>+<keycap>F<x></keycap>) then switch to your previous console by the same way. </simpara></listitem> @@ -1363,16 +1354,18 @@ <sect2 id="vidix"> <title>VIDIX</title> -<formalpara> -<title>PREAMBLE</title> +<formalpara><title>PREAMBLE</title> <para> -<acronym>VIDIX</acronym> is the abbreviation for <emphasis role="bold">VID</emphasis>eo -<emphasis role="bold">I</emphasis>nterface for *ni<emphasis role="bold">X</emphasis>. +<acronym>VIDIX</acronym> is the abbreviation for +<emphasis role="bold">VID</emphasis>eo +<emphasis role="bold">I</emphasis>nterface +for *ni<emphasis role="bold">X</emphasis>. VIDIX was designed and introduced as an interface for fast user-space drivers -providing such video performance as mga_vid does for Matrox cards. It's also very -portable. +providing such video performance as mga_vid does for Matrox cards. It's also +very portable. </para> </formalpara> + <para> This interface was designed as an attempt to fit existing video acceleration interfaces (known as mga_vid, rage128_vid, radeon_vid, @@ -1443,8 +1436,7 @@ </simpara></listitem> </itemizedlist> -<formalpara> -<title>USAGE METHODS</title> +<formalpara><title>USAGE METHODS</title> <para> When VIDIX is used as <emphasis role="bold">subdevice</emphasis> (<option>-vo vesa:vidix</option>) then video mode configuration is performed by video @@ -1460,9 +1452,13 @@ <para> Also you can specify VIDIX's driver directly as third subargument in command line: -<screen>mplayer -vo xvidix:mga_vid.so -fs -zoom -double <replaceable>file.avi</replaceable></screen> +<screen> +mplayer -vo xvidix:mga_vid.so -fs -zoom -double <replaceable>file.avi</replaceable> +</screen> or -<screen>mplayer -vo vesa:vidix:radeon_vid.so -fs -zoom -double -bpp 32 <replaceable>file.avi</replaceable></screen> +<screen> +mplayer -vo vesa:vidix:radeon_vid.so -fs -zoom -double -bpp 32 <replaceable>file.avi</replaceable> +</screen> But it's dangerous, and you shouldn't do that. In this case given driver will be forced and result is unpredictable (it may <emphasis role="bold">freeze</emphasis> your computer). You should do that @@ -1481,29 +1477,34 @@ <procedure> <step><para> - Download the <ulink url="http://www.arava.co.il/matan/svgalib/">development version</ulink> + Download the + <ulink url="http://www.arava.co.il/matan/svgalib/">development version</ulink> of svgalib (for example 1.9.17), <emphasis role="bold">OR</emphasis> - download a version made by Alex especially for usage with <application>MPlayer</application> - (it doesn't need the svgalib source to compile) from + download a version made by Alex especially for usage with + <application>MPlayer</application> (it doesn't need the svgalib source to + compile) from <ulink url="http://www.mplayerhq.hu/MPlayer/contrib/svgalib/svgalib_helper-1.9.17-mplayer.tar.bz2">here</ulink>. </para></step> <step><para> - Compile the module in the <filename class="directory">svgalib_helper</filename> - directory (it can be found inside the <filename class="directory">svgalib-1.9.17/kernel/</filename> - directory if you've downloaded the source from the svgalib site) and insmod it. + Compile the module in the + <filename class="directory">svgalib_helper</filename> directory (it can be + found inside the + <filename class="directory">svgalib-1.9.17/kernel/</filename> directory if + you've downloaded the source from the svgalib site) and insmod it. </para></step> <step><para> - To create the necessary devices in the <filename class="directory">/dev</filename> - directory, do a <screen>make device</screen> in the <filename class="directory">svgalib_helper</filename> - dir, as root. + To create the necessary devices in the + <filename class="directory">/dev</filename> directory, do a + <screen>make device</screen> in the + <filename class="directory">svgalib_helper</filename> dir, as root. </para></step> <step><para> Move the <filename class="directory">svgalib_helper</filename> directory to <filename class="directory">mplayer/main/libdha/svgalib_helper</filename>. </para></step> <step><para> - Required if you download the source from the svgalib site: Remove the comment before the - CFLAGS line containing "svgalib_helper" string from the + Required if you download the source from the svgalib site: Remove the comment + before the CFLAGS line containing "svgalib_helper" string from the <filename class="directory">libdha/Makefile</filename>. </para></step> <step><para> @@ -1571,11 +1572,11 @@ <title>nVidia cards</title> <para> - An unique feature of the nvidia_vid driver is its ability to display video on - <emphasis role="bold">plain, pure, text-only console</emphasis> - with no - framebuffer or X magic whatsoever. For this purpose, we'll have to use the - <option>cvidix</option> video output, as the following example shows: - <screen>mplayer -vo cvidix <replaceable>example.avi</replaceable></screen> +An unique feature of the nvidia_vid driver is its ability to display video on +<emphasis role="bold">plain, pure, text-only console</emphasis> - with no +framebuffer or X magic whatsoever. For this purpose, we'll have to use the +<option>cvidix</option> video output, as the following example shows: +<screen>mplayer -vo cvidix <replaceable>example.avi</replaceable></screen> </para> </sect3> @@ -1606,23 +1607,24 @@ <blockquote><para> "DirectFB is a graphics library which was designed with embedded systems in mind. It offers maximum hardware accelerated performance at a minimum -of resource usage and overhead." - quoted from <ulink url="http://www.directfb.org"/> +of resource usage and overhead." - quoted from +<ulink url="http://www.directfb.org"/> </para></blockquote> <para>I'll exclude DirectFB features from this section.</para> <para> Though <application>MPlayer</application> is not supported as a "video -provider" in DirectFB, this output driver will enable video playback through -DirectFB. It will - of course - be accelerated, on my Matrox G400 DirectFB's speed -was the same as XVideo. +provider" in DirectFB, this output driver will enable video playback +through DirectFB. It will - of course - be accelerated, on my Matrox G400 +DirectFB's speed was the same as XVideo. </para> <para> -Always try to use the newest version of DirectFB. You can use DirectFB options on -the command line, using the <option>-dfbopts</option> option. Layer selection can -be done by the subdevice method, e.g.: <option>-vo directfb:2</option> -(layer -1 is default: autodetect) +Always try to use the newest version of DirectFB. You can use DirectFB options +on the command line, using the <option>-dfbopts</option> option. Layer +selection can be done by the subdevice method, e.g.: +<option>-vo directfb:2</option> (layer -1 is default: autodetect) </para> </sect2> @@ -1632,8 +1634,8 @@ <title>DirectFB/Matrox (dfbmga)</title> <para> -Please read the <link linkend="directfb">main DirectFB</link> section for general -information. +Please read the <link linkend="directfb">main DirectFB</link> section for +general information. </para> <para> @@ -1673,78 +1675,68 @@ <para> <application>MPlayer</application> supports cards with the Siemens DVB chipset from vendors like Siemens, Technotrend, Galaxis or Hauppauge. The latest DVB -drivers are available from the <ulink url="http://www.linuxtv.org">Linux TV site</ulink>. +drivers are available from the +<ulink url="http://www.linuxtv.org">Linux TV site</ulink>. If you want to do software transcoding you should have at least a 1GHz CPU. </para> <para> Configure should detect your DVB card. If it did not, force detection with -</para> - -<para><screen>./configure --enable-dvb</screen></para> - -<para>If you have ost headers at a non-standard path, set the path with</para> +<screen>./configure --enable-dvb</screen> +If you have ost headers at a non-standard path, set the path with +<screen> +./configure --with-extraincdir=<replaceable>DVB source directory</replaceable>/ost/include +</screen> +Then compile and install as usual.</para> -<para><screen>./configure --with-extraincdir=<replaceable>DVB source directory</replaceable>/ost/include -</screen></para> - -<para>Then compile and install as usual.</para> - -<formalpara> -<title>USAGE</title> +<formalpara><title>USAGE</title> <para> -Hardware decoding (playing standard MPEG-1/2 files) can be done with this command: +Hardware decoding (playing standard MPEG-1/2 files) can be done with this +command: +<screen> +mplayer -ao mpegpes -vo mpegpes <replaceable>file.mpg|vob</replaceable> +</screen> </para> </formalpara> <para> -<screen>mplayer -ao mpegpes -vo mpegpes <replaceable>file.mpg|vob</replaceable></screen> -</para> - -<para> -Software decoding or transcoding different formats to MPEG-1 can be achieved using -a command like this: -</para> -<para><screen> +Software decoding or transcoding different formats to MPEG-1 can be achieved +using a command like this: +<screen> mplayer -ao mpegpes -vo mpegpes <replaceable>yourfile.ext</replaceable> mplayer -ao mpegpes -vo mpegpes -vf expand <replaceable>yourfile.ext</replaceable> </screen></para> <para> Note that DVB cards only support heights 288 and 576 for PAL or 240 and 480 for -NTSC. You <emphasis role="bold">must</emphasis> rescale for other heights by adding -<option>scale=width:height</option> with the width and height you want to the -<option>-vf</option> option. DVB cards accept various widths, like 720, 704, -640, 512, 480, 352 etc. and do hardware scaling in horizontal direction, so you -do not need to scale horizontally in most cases. For a 512x384 (aspect 4:3) -MPEG-4 (DivX) try: -</para> - -<para><screen>mplayer -ao mpegpes -vo mpegpes -vf scale=512:576</screen></para> - -<para>If you have a widescreen movie and you do not want to scale it to full height, -you can use the <option>expand=w:h</option> filter to add black bands. To view a -640x384 MPEG-4 (DivX), try: +NTSC. You <emphasis role="bold">must</emphasis> rescale for other heights by +adding <option>scale=width:height</option> with the width and height you want +to the <option>-vf</option> option. DVB cards accept various widths, like 720, +704, 640, 512, 480, 352 etc. and do hardware scaling in horizontal direction, +so you do not need to scale horizontally in most cases. +For a 512x384 (aspect 4:3) MPEG-4 (DivX) try: +<screen>mplayer -ao mpegpes -vo mpegpes -vf scale=512:576</screen> </para> <para> -<screen>mplayer -ao mpegpes -vo mpegpes -vf expand=640:576 <replaceable>file.avi</replaceable> +If you have a widescreen movie and you do not want to scale it to full height, +you can use the <option>expand=w:h</option> filter to add black bands. To view a +640x384 MPEG-4 (DivX), try: +<screen> +mplayer -ao mpegpes -vo mpegpes -vf expand=640:576 <replaceable>file.avi</replaceable> </screen> </para> <para> If your CPU is too slow for a full size 720x576 MPEG-4 (DivX), try downscaling: -</para> - -<para> -<screen>mplayer -ao mpegpes -vo mpegpes -vf scale=352:576 <replaceable>file.avi</replaceable> +<screen> +mplayer -ao mpegpes -vo mpegpes -vf scale=352:576 <replaceable>file.avi</replaceable> </screen> </para> -<para>If speed does not improve, try vertical downscaling, too:</para> - -<para> -<screen>mplayer -ao mpegpes -vo mpegpes -vf scale=352:288 <replaceable>file.avi</replaceable> +<para>If speed does not improve, try vertical downscaling, too: +<screen> +mplayer -ao mpegpes -vo mpegpes -vf scale=352:288 <replaceable>file.avi</replaceable> </screen> </para> @@ -1753,8 +1745,9 @@ <option>expand=w:h</option> or <option>expand=w:h:x:y</option>, use <option>expand=w:h:x:y:1</option> (the 5th parameter <option>:1</option> at the end will enable OSD rendering). You may want to move the image up a bit -to get a bigger black zone for subtitles. You may also want to move subtitles up, -if they are outside your TV screen, use the <option>-subpos <0-100></option> +to get a bigger black zone for subtitles. You may also want to move subtitles +up, if they are outside your TV screen, use the +<option>-subpos <0-100></option> option to adjust this (<option>-subpos 80</option> is a good choice). </para> @@ -1767,140 +1760,127 @@ To keep the aspect ratio of MPEG-4 (DivX) files and get the optimal scaling parameters (hardware horizontal scaling and software vertical scaling while keeping the right aspect ratio), use the new dvbscale filter: -</para> - -<para><screen> +<screen> for a 4:3 TV: -vf dvbscale,scale=-1:0,expand=-1:576:-1:-1:1 for a 16:9 TV: -vf dvbscale=1024,scale=-1:0,expand=-1:576:-1:-1:1 -</screen></para> +</screen> +</para> -<formalpara> -<title>Digital TV (DVB input module)</title> +<formalpara><title>Digital TV (DVB input module)</title> <para>You can use your DVB card for watching Digital TV.</para> </formalpara> <para> - You should have the programs <command>scan</command> and - <command>szap/tzap/czap/azap</command> installed; they are all included in - the drivers package. +You should have the programs <command>scan</command> and +<command>szap/tzap/czap/azap</command> installed; they are all included in +the drivers package. </para> <para> - Verify that your drivers are working properly with a program such as - <ulink url="http://sf.net/projects/dvbtools/"><command>dvbstream</command></ulink> - (that is the base of the DVB input module). +Verify that your drivers are working properly with a program such as +<ulink url="http://sf.net/projects/dvbtools/"><command>dvbstream</command></ulink> +(that is the base of the DVB input module). </para> <para> - Now you should compile a <filename>~/.mplayer/channels.conf</filename> - file, with the syntax accepted by <command>szap/tzap/czap/azap</command>, or - have <command>scan</command> compile it for you. +Now you should compile a <filename>~/.mplayer/channels.conf</filename> +file, with the syntax accepted by <command>szap/tzap/czap/azap</command>, or +have <command>scan</command> compile it for you. </para> <para> - If you have more than one card type (e.g. Satellitar, Terrestrial, Cable and ATSC) - you can save your channels files as - <filename>~/.mplayer/channels.conf.sat</filename>, - <filename>~/.mplayer/channels.conf.ter</filename>, - <filename>~/.mplayer/channels.conf.cbl</filename>, - and <filename>~/.mplayer/channels.conf.atsc</filename>, - respectively, so as to implicitly hint <application>MPlayer</application> - to use these files rather than <filename>~/.mplayer/channels.conf</filename>, - and you only need to specify which card to use. +If you have more than one card type (e.g. Satellitar, Terrestrial, Cable and ATSC) +you can save your channels files as +<filename>~/.mplayer/channels.conf.sat</filename>, +<filename>~/.mplayer/channels.conf.ter</filename>, +<filename>~/.mplayer/channels.conf.cbl</filename>, +and <filename>~/.mplayer/channels.conf.atsc</filename>, +respectively, so as to implicitly hint <application>MPlayer</application> +to use these files rather than <filename>~/.mplayer/channels.conf</filename>, +and you only need to specify which card to use. </para> <para> - Make sure that you have have <emphasis>only</emphasis> Free to Air - channels in your <filename>channels.conf</filename> file, or - <application>MPlayer</application> will try to skip to the next visible one, - but it may take long if there are many consecutive encrypted channels. +Make sure that you have have <emphasis>only</emphasis> Free to Air +channels in your <filename>channels.conf</filename> file, or +<application>MPlayer</application> will try to skip to the next visible one, +but it may take long if there are many consecutive encrypted channels. </para> <para> - In your audio and video fields you can use an extended syntax: - <option>...:pid[+pid]:...</option> (for a maximum of 6 pids each); - in this case <application>MPlayer</application> will include in the - stream all the indicated pids, plus pid 0 (that contains the PAT). - You are encouraged to include in each row the PMT pid for the - corresponding channel (if you know it). - Other possible uses are: televideo pid, second audio track, etc. -</para> - -<para> - If <application>MPlayer</application> complains frequently about - <screen>Too many video/audio packets in the buffer</screen> or - if you notice a growing desynchronization between audio and - video try to use the libavformat MPEG-TS demuxer by adding - <option>-demuxer lavf -lavfdopts probesize=128</option> - to your command line. +In your audio and video fields you can use an extended syntax: +<option>...:pid[+pid]:...</option> (for a maximum of 6 pids each); +in this case <application>MPlayer</application> will include in the +stream all the indicated pids, plus pid 0 (that contains the PAT). +You are encouraged to include in each row the PMT pid for the +corresponding channel (if you know it). +Other possible uses are: televideo pid, second audio track, etc. </para> <para> - To show the first of the channels present in your list, run +If <application>MPlayer</application> complains frequently about +<screen>Too many video/audio packets in the buffer</screen> or +if you notice a growing desynchronization between audio and +video try to use the libavformat MPEG-TS demuxer by adding +<option>-demuxer lavf -lavfdopts probesize=128</option> +to your command line. </para> -<screen> - mplayer dvb:// -</screen> - <para> - If you want to watch a specific channel, such as R1, run +To show the first of the channels present in your list, run +<screen>mplayer dvb://</screen> </para> -<screen> - mplayer dvb://R1 -</screen> - <para> - If you have more than one card you also need to specify the number of the card - where the channel is visible (e.g. 2) with the syntax: +If you want to watch a specific channel, such as R1, run +<screen>mplayer dvb://<replaceable>R1</replaceable></screen> </para> -<screen> - mplayer dvb://2@R1 -</screen> +<para> +If you have more than one card you also need to specify the number of the card +where the channel is visible (e.g. 2) with the syntax: +<screen>mplayer dvb://<replaceable>2@R1</replaceable></screen> +</para> <para> - To change channels press the <keycap>h</keycap> (next) and - <keycap>k</keycap> (previous) keys, or use the - <link linkend="osdmenu">OSD menu</link>. +To change channels press the <keycap>h</keycap> (next) and +<keycap>k</keycap> (previous) keys, or use the +<link linkend="osdmenu">OSD menu</link>. </para> <para> - If your <filename>~/.mplayer/menu.conf</filename> contains a - <literal><dvbsel></literal> entry, such as the one in the example - file <filename>etc/dvb-menu.conf</filename> (that you can use to overwrite - <filename>~/.mplayer/menu.conf</filename>), the main menu will show a - sub-menu entry that will permit you to choose one of the channels present - in your <filename>channels.conf</filename>, possibly preceded by a menu - with the list of cards available if more than one is usable by - <application>MPlayer</application>. +If your <filename>~/.mplayer/menu.conf</filename> contains a +<literal><dvbsel></literal> entry, such as the one in the example +file <filename>etc/dvb-menu.conf</filename> (that you can use to overwrite +<filename>~/.mplayer/menu.conf</filename>), the main menu will show a +sub-menu entry that will permit you to choose one of the channels present +in your <filename>channels.conf</filename>, possibly preceded by a menu +with the list of cards available if more than one is usable by +<application>MPlayer</application>. </para> <para> - If you want to save a program to disk you can use -</para> - +If you want to save a program to disk you can use <screen> - mplayer -dumpfile r1.ts -dumpstream dvb://R1 +mplayer -dumpfile <replaceable>r1.ts</replaceable> -dumpstream dvb://<replaceable>R1</replaceable> </screen> - -<para> - If you want to record it in a different format (re-encoding it) instead - you can run a command such as </para> +<para> +If you want to record it in a different format (re-encoding it) instead +you can run a command such as <screen> - mencoder -o r1.avi -ovc xvid -xvidencopts bitrate=800 -oac mp3lame -lameopts cbr:br=128 -pp=ci dvb://R1 +mencoder -o <replaceable>r1.avi</replaceable> -ovc xvid -xvidencopts bitrate=800 \ + -oac mp3lame -lameopts cbr:br=128 -pp=ci dvb://<replaceable>R1</replaceable> </screen> +</para> <para> - Read the man page for a list of options that you can pass to the - DVB input module. +Read the man page for a list of options that you can pass to the +DVB input module. </para> -<formalpara> -<title>FUTURE</title> +<formalpara><title>FUTURE</title> <para> If you have questions or want to hear feature announcements and take part in discussions on this subject, join our @@ -1922,29 +1902,31 @@ <sect2 id="dxr2"> <title>DXR2</title> -<para><application>MPlayer</application> supports hardware accelerated playback - with the Creative DXR2 card.</para> +<para> +<application>MPlayer</application> supports hardware accelerated playback +with the Creative DXR2 card. +</para> + <para> First of all you will need properly installed DXR2 drivers. You can find the drivers and installation instructions at the <ulink url="http://dxr2.sf.net/">DXR2 Resource Center</ulink> site. </para> -<variablelist> -<title>USAGE</title> +<variablelist><title>USAGE</title> <varlistentry> -<term><option>-vo dxr2</option></term> -<listitem><para>Enable TV output.</para></listitem> + <term><option>-vo dxr2</option></term> + <listitem><para>Enable TV output.</para></listitem> </varlistentry> - <varlistentry> -<term><option>-vo dxr2:x11</option> or <option>-vo dxr2:xv</option></term> -<listitem><para>Enable Overlay output in X11.</para></listitem> + <term><option>-vo dxr2:x11</option> or <option>-vo dxr2:xv</option></term> + <listitem><para>Enable Overlay output in X11.</para></listitem> </varlistentry> - <varlistentry> -<term><option>-dxr2 <option1:option2:...></option></term> -<listitem><para>This option is used to control the DXR2 driver.</para></listitem> + <term><option>-dxr2 <option1:option2:...></option></term> + <listitem><para> + This option is used to control the DXR2 driver. + </para></listitem> </varlistentry> </variablelist> @@ -1993,11 +1975,13 @@ will be supported by the <application>MPlayer</application> GUI in the future. When overlay is properly set up you will no longer need to use dxr3view. <option>prebuf</option> turns on prebuffering. Prebuffering is a feature of the -em8300 chip that enables it to hold more than one frame of video at a time. This -means that when you are running with prebuffering <application>MPlayer</application> -will try to keep the video buffer filled with data at all times. If you are on -a slow machine <application>MPlayer</application> will probably use close to, -or precisely 100% of CPU. This is especially common if you play pure MPEG streams +em8300 chip that enables it to hold more than one frame of video at a time. +This means that when you are running with prebuffering +<application>MPlayer</application> will try to keep the video buffer filled +with data at all times. +If you are on a slow machine <application>MPlayer</application> will probably +use close to, or precisely 100% of CPU. +This is especially common if you play pure MPEG streams (like DVDs, SVCDs a.s.o.) since <application>MPlayer</application> will not have to reencode it to MPEG it will fill the buffer very fast. With prebuffering video playback is <emphasis role="bold">much</emphasis> @@ -2007,79 +1991,84 @@ so it is highly suggested that you turn on <application>MPlayer</application>'s <option>-framedrop</option> option to avoid further loss of sync. <option>sync</option> will turn on the new sync-engine. This is currently an -experimental feature. With the sync feature turned on the em8300's internal clock -will be monitored at all times, if it starts to deviate from -<application>MPlayer</application>'s clock it will be reset causing the em8300 to -drop any frames that are lagging behind. +experimental feature. With the sync feature turned on the em8300's internal +clock will be monitored at all times, if it starts to deviate from +<application>MPlayer</application>'s clock it will be reset causing the em8300 +to drop any frames that are lagging behind. <option>norm=x</option> will set the TV norm of the DXR3 card without the need for external tools like em8300setup. Valid norms are 5 = NTSC, 4 = PAL-60, 3 = PAL. Special norms are 2 (auto-adjust using PAL/PAL-60) and 1 (auto-adjust using PAL/NTSC) because they decide which norm to use by looking at the frame rate of the movie. norm = 0 (default) does not change the current norm. -<option><replaceable>device</replaceable></option> = device number to use if you have more than one em8300 -card. -Any of these options may be left out. -<option>:prebuf:sync</option> seems to work great when playing MPEG-4 (DivX) movies. People -have reported problems using the prebuf option when playing MPEG-1/2 files. You -might want to try running without any options first, if you have sync problems, -or DVD subtitle problems, give <option>:sync</option> a try. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>-ao oss:/dev/em8300_ma-<replaceable>X</replaceable></option></term> -<listitem><para> -For audio output, where <replaceable>X</replaceable> is the device number (0 if one card). -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>-af resample=<replaceable>xxxxx</replaceable></option></term> -<listitem><para> -The em8300 cannot play back samplerates lower than 44100Hz. If the sample -rate is below 44100Hz select either 44100Hz or 48000Hz depending on which -one matches closest. I.e. if the movie uses 22050Hz use 44100Hz as -44100 / 2 = 22050, if it is 24000Hz use 48000Hz as 48000 / 2 = 24000 and so on. -This does not work with digital audio output (<option>-ac hwac3</option>). +<option><replaceable>device</replaceable></option> = device number to use if +you have more than one em8300 card. Any of these options may be left out. +<option>:prebuf:sync</option> seems to work great when playing MPEG-4 (DivX) +movies. People have reported problems using the prebuf option when playing +MPEG-1/2 files. +You might want to try running without any options first, if you have sync +problems, or DVD subtitle problems, give <option>:sync</option> a try. </para></listitem> </varlistentry> <varlistentry> -<term><option>-vf lavc</option></term> -<listitem><para> -To watch non-MPEG content on the em8300 (i.e. MPEG-4 (DivX) or RealVideo) -you have to specify an MPEG-1 video filter such as -<systemitem class="library">libavcodec</systemitem> (lavc). -See the man page for further info about <option>-vf lavc</option>. -Currently there is no way of setting the fps -of the em8300 which means that it is fixed to 30000/1001 fps. Because of this it is -highly recommended that you use <option>-vf lavc=<replaceable>quality</replaceable>:25</option> -especially if you are using prebuffering. Then why 25 and not 30000/1001? Well, the -thing is that when you use 30000/1001 the picture becomes a bit jumpy. The reason for -this is unknown to us. If you set it to somewhere between 25 and 27 the picture -becomes stable. For now all we can do is accept this for a fact. -</para></listitem> + <term><option>-ao oss:/dev/em8300_ma-<replaceable>X</replaceable></option></term> + <listitem><para> + For audio output, where <replaceable>X</replaceable> is the device number + (0 if one card). + </para></listitem> +</varlistentry> + +<varlistentry> + <term><option>-af resample=<replaceable>xxxxx</replaceable></option></term> + <listitem><para> + The em8300 cannot play back samplerates lower than 44100Hz. If the sample + rate is below 44100Hz select either 44100Hz or 48000Hz depending on which + one matches closest. I.e. if the movie uses 22050Hz use 44100Hz as + 44100 / 2 = 22050, if it is 24000Hz use 48000Hz as 48000 / 2 = 24000 + and so on. + This does not work with digital audio output (<option>-ac hwac3</option>). + </para></listitem> </varlistentry> <varlistentry> -<term><option>-vf expand=-1:-1:-1:-1:1</option></term> -<listitem><para> -Although the DXR3 driver can put some OSD onto the MPEG-1/2/4 video, it has -much lower quality than <application>MPlayer</application>'s traditional OSD, -and has several refresh problems as well. The command line above will firstly -convert the input video to MPEG-4 (this is mandatory, sorry), then apply an -expand filter which won't expand anything (-1: default), but apply the normal -OSD onto the picture (that's what the "1" at the end does). -</para></listitem> + <term><option>-vf lavc</option></term> + <listitem><para> + To watch non-MPEG content on the em8300 (i.e. MPEG-4 (DivX) or RealVideo) + you have to specify an MPEG-1 video filter such as + <systemitem class="library">libavcodec</systemitem> (lavc). + See the man page for further info about <option>-vf lavc</option>. + Currently there is no way of setting the fps of the em8300 which means that + it is fixed to 30000/1001 fps. + Because of this it is highly recommended that you use + <option>-vf lavc=<replaceable>quality</replaceable>:25</option> + especially if you are using prebuffering. Then why 25 and not 30000/1001? + Well, the thing is that when you use 30000/1001 the picture becomes a bit + jumpy. + The reason for this is unknown to us. + If you set it to somewhere between 25 and 27 the picture becomes stable. + For now all we can do is accept this for a fact. + </para></listitem> </varlistentry> <varlistentry> -<term><option>-ac hwac3</option></term> -<listitem><para> -The em8300 supports playing back AC3 audio (surround sound) through the -digital audio output of the card. See the <option>-ao oss</option> option above, -it must be used to specify the DXR3's output instead of a sound card. -</para></listitem> + <term><option>-vf expand=-1:-1:-1:-1:1</option></term> + <listitem><para> + Although the DXR3 driver can put some OSD onto the MPEG-1/2/4 video, it has + much lower quality than <application>MPlayer</application>'s traditional OSD, + and has several refresh problems as well. The command line above will firstly + convert the input video to MPEG-4 (this is mandatory, sorry), then apply an + expand filter which won't expand anything (-1: default), but apply the normal + OSD onto the picture (that's what the "1" at the end does). + </para></listitem> +</varlistentry> + +<varlistentry> + <term><option>-ac hwac3</option></term> + <listitem><para> + The em8300 supports playing back AC3 audio (surround sound) through the + digital audio output of the card. See the <option>-ao oss</option> option + above, it must be used to specify the DXR3's output instead of a sound card. + </para></listitem> </varlistentry> </variablelist> </sect2> @@ -2113,10 +2102,12 @@ <para> This driver talks to the kernel driver available at <ulink url="http://mjpeg.sf.net"/>, so -you must get it working first. The presence of an MJPEG card is autodetected by the -<filename>configure</filename> script, if autodetection fails, force detection with +you must get it working first. The presence of an MJPEG card is autodetected by +the <filename>configure</filename> script, if autodetection fails, force +detection with <screen>./configure --enable-zr</screen> </para> + <para> The output can be controlled by several options, a long description of the options can be found in the man page, a short list of options can be viewed @@ -2155,9 +2146,10 @@ </para> <para> -Extra occurrences of <option>-zrcrop</option> invoke <emphasis>cinerama</emphasis> -mode, i.e. you can distribute the movie over several TV's or beamers to create a -larger screen. Suppose you have two beamers. The left one is connected to your +Extra occurrences of <option>-zrcrop</option> invoke +<emphasis>cinerama</emphasis> mode, i.e. you can distribute the movie over +several TV's or beamers to create a larger screen. +Suppose you have two beamers. The left one is connected to your Buz at <filename>/dev/video1</filename> and the right one is connected to your DC10+ at <filename>/dev/video0</filename>. The movie has a resolution of 704x288. Suppose also that you want the right beamer in black and white and @@ -2165,8 +2157,8 @@ issue the following command <screen> mplayer -vo zr -zrdev /dev/video0 -zrcrop 352x288+352+0 -zrxdoff 0 -zrbw \ - -zrcrop 352x288+0+0 -zrdev /dev/video1 -zrquality 10 \ - <replaceable>movie.avi</replaceable> + -zrcrop 352x288+0+0 -zrdev /dev/video1 -zrquality 10 \ + <replaceable>movie.avi</replaceable> </screen> </para> @@ -2181,8 +2173,9 @@ <para> Finally an important remark: Do not start or stop XawTV on the playback device during playback, it will crash your computer. It is, however, fine to -<emphasis role="bold">FIRST</emphasis> start XawTV, <emphasis role="bold">THEN</emphasis> -start <application>MPlayer</application>, wait for <application>MPlayer</application> +<emphasis role="bold">FIRST</emphasis> start XawTV, +<emphasis role="bold">THEN</emphasis> start <application>MPlayer</application>, +wait for <application>MPlayer</application> to finish and <emphasis role="bold">THEN</emphasis> stop XawTV. </para> </sect2> @@ -2230,22 +2223,26 @@ <variablelist> <varlistentry> <term>XFree86</term> - <listitem><para> + <listitem> + <para> Using the driver and the HAL module, available from the <ulink url="http://www.matrox.com">Matrox site</ulink>. This will give you X on the TV. - </para><para> + </para> + <para> <emphasis role="bold">This method doesn't give you accelerated playback</emphasis> - as under Windows! The second head has only YUV framebuffer, the <emphasis>BES</emphasis> - (Back End Scaler, the YUV scaler on G200/G400/G450/G550 cards) doesn't - work on it! The windows driver somehow workarounds this, probably by - using the 3D engine to zoom, and the YUV framebuffer to display the - zoomed image. If you really want to use X, use the <option>-vo x11 -fs - -zoom</option> options, but it will be <emphasis role="bold">SLOW</emphasis>, - and has <emphasis role="bold">Macrovision</emphasis> copy protection enabled + as under Windows! The second head has only YUV framebuffer, the + <emphasis>BES</emphasis> (Back End Scaler, the YUV scaler on + G200/G400/G450/G550 cards) doesn't work on it! The windows driver somehow + workarounds this, probably by using the 3D engine to zoom, and the YUV + framebuffer to display the zoomed image. If you really want to use X, use + the <option>-vo x11 -fs -zoom</option> options, but it will be + <emphasis role="bold">SLOW</emphasis>, and has + <emphasis role="bold">Macrovision</emphasis> copy protection enabled (you can "workaround" Macrovision using this <ulink url="http://avifile.sf.net/mgamacro.pl">perl script</ulink>). - </para></listitem> + </para> + </listitem> </varlistentry> <varlistentry> <term>Framebuffer</term> @@ -2253,8 +2250,9 @@ <para> Using the <emphasis role="bold">matroxfb modules</emphasis> in the 2.4 kernels. 2.2 kernels don't have the TVout feature in them, thus unusable - for this. You have to enable ALL matroxfb-specific feature during compilation - (except MultiHead), and compile them into <emphasis role="bold">modules</emphasis>! + for this. You have to enable ALL matroxfb-specific feature during + compilation (except MultiHead), and compile them into + <emphasis role="bold">modules</emphasis>! You'll also need I2C enabled. </para> @@ -2276,8 +2274,8 @@ somewhere into your <envar>PATH</envar>. </para></step> <step><para> - Then enter into the <filename class="directory">TVout/</filename> directory - in the <application>MPlayer</application> source, and execute + Then enter into the <filename class="directory">TVout/</filename> + directory in the <application>MPlayer</application> source, and execute <filename>./modules</filename> as root. Your text-mode console will enter into framebuffer mode (no way back!). </para></step> @@ -2320,7 +2318,7 @@ <keycap>Ctrl</keycap>+<keycap>Alt</keycap>+<keycap>F1</keycap>.) Change <literal>640</literal> and <literal>512</literal> if you set the resolution to other... - </para></step> + </para></step> <step><para> <emphasis role="bold">Enjoy the ultra-fast ultra-featured Matrox TV output (better than Xv)!</emphasis> @@ -2330,16 +2328,14 @@ </varlistentry> </variablelist> -<formalpara> -<title>Building a Matrox TV-out cable</title> +<formalpara><title>Building a Matrox TV-out cable</title> <para> No one takes any responsibility, nor guarantee for any damage caused by this documentation. </para> </formalpara> -<formalpara> -<title>Cable for G400</title> +<formalpara><title>Cable for G400</title> <para> The CRTC2 connector's fourth pin is the composite video signal. The ground are the sixth, seventh and eighth pins. (info contributed @@ -2347,8 +2343,7 @@ </para> </formalpara> -<formalpara> -<title>Cable for G450</title> +<formalpara><title>Cable for G450</title> <para> The CRTC2 connector's first pin is the composite video signal. The ground are the fifth, sixth, seventh, and fifteenth (5, 6, 7, 15) @@ -2364,13 +2359,14 @@ <para> TV output support for these cards has only been recently introduced, and is -not yet in the mainstream kernel. Currently the <emphasis role="bold">mga_vid</emphasis> -module can't be used AFAIK, because the G450/G550 driver works only in one -configuration: the first CRTC chip (with much more features) on the first display -(on monitor), and the second CRTC (no <emphasis role="bold">BES</emphasis> - for +not yet in the mainstream kernel. +Currently the <emphasis role="bold">mga_vid</emphasis> module can't be used +AFAIK, because the G450/G550 driver works only in one configuration: the first +CRTC chip (with much more features) on the first display (on monitor), +and the second CRTC (no <emphasis role="bold">BES</emphasis> - for explanation on BES, please see the G400 section above) on TV. So you can only -use <application>MPlayer</application>'s <emphasis>fbdev</emphasis> output driver -at the present. +use <application>MPlayer</application>'s <emphasis>fbdev</emphasis> output +driver at the present. </para> <para> @@ -2391,8 +2387,7 @@ <sect2 id="tvout-ati"> <title>ATI cards</title> -<formalpara> -<title>PREAMBLE</title> +<formalpara><title>PREAMBLE</title> <para> Currently ATI doesn't want to support any of its TV-out chips under Linux, because of their licensed Macrovision technology. @@ -2417,7 +2412,8 @@ </simpara></listitem> <listitem><simpara> <emphasis role="bold">Rage Mobility P/M, Radeon, Rage 128, Mobility M3/M4</emphasis>: - supported by <ulink url="http://www.stud.uni-hamburg.de/users/lennart/projects/atitvout/">atitvout</ulink>. + supported by + <ulink url="http://www.stud.uni-hamburg.de/users/lennart/projects/atitvout/">atitvout</ulink>. </simpara></listitem> </itemizedlist> @@ -2439,9 +2435,10 @@ <title>nVidia</title> <para> -First, you MUST download the closed-source drivers from <ulink url="http://nvidia.com"/>. -I will not describe the installation and configuration process because it does not cover -the scope of this documentation. +First, you MUST download the closed-source drivers from +<ulink url="http://nvidia.com"/>. +I will not describe the installation and configuration process because it does +not cover the scope of this documentation. </para> <para>