XML version of MPlayer's doc

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

1 files changed, 203 insertions, 0 deletions

diff --git a/DOCS/xml/en/tvinput.xml b/DOCS/xml/en/tvinput.xml
new file mode 100644
index 0000000000..a0b7efd997
--- /dev/null
+++ b/DOCS/xml/en/tvinput.xml
@@ -0,0 +1,203 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<sect1 id="tv-input" xreflabel="TV input">
+<title>TV input</title>
+
+<para>
+This section is about how to enable <emphasis role="bold">watching/grabbing
+from V4L compatible TV tuner</emphasis>.
+</para>
+
+
+<sect2 id="tv-compilation">
+<title>Compilation</title>
+
+<procedure>
+<step><para>
+  First, you have to recompile. <filename>./configure</filename> will
+  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>
+<step><para>
+  Make sure your tuner works with another TV software in Linux, for
+  example xawtv.
+  </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 on: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
+&quot;_&quot; 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), make sure you turned
+deinterlacing on. 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>-vop 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>
+Watch out for CPU load. It shouldn't cross the 90% boundary for most of the
+time. If you have a large capture buffer, MEncoder 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), MEncoder 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 libavcodec 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 soundcard 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 MPlayer'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 soundcard
+(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>
+Dummy output, to AAlib :)
+<screen>
+mplayer -tv on:driver=dummy:width=640:height=480 -vo aa<!--
+--></screen>
+</para>
+</informalexample>
+
+<informalexample>
+<para>
+Input from standard V4L:
+<screen>
+mplayer -tv on:driver=v4l:width=640:height=480:outfmt=i420 -vc rawi420 -vo xv<!--
+--></screen>
+</para>
+</informalexample>
+
+<informalexample>
+<para>
+A more sophisticated example. This makes MEncoder 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 on:driver=v4l:width=768:height=576 \
+     -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=900 \
+     -oac mp3lame -lameopts cbr:br=64 \
+     -vop pp=lb,crop=720:544:24:16 -o output.avi
+</screen>
+</para>
+</informalexample>
+
+<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 actualy 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 on:driver=v4l:width=768:height=576 \
+     -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=350:vhq:vqmax=31:keyint=300 \
+     -oac mp3lame -lameopts cbr:br=48 \
+     -vop scale=384:288,pp=tn/lb,crop=720:540:24:18 -sws 1 -o output.avi 
+</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>
+</sect2>
+</sect1>