<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY appversion		"0.10">
  <!ENTITY manrevision		"0.3">
  <!ENTITY date			"2005-02-18">

  <!ENTITY settings		SYSTEM "settings.xml">
  <!ENTITY channel-editor	SYSTEM "channel-editor.xml">
  <!ENTITY zapzilla		SYSTEM "zapzilla.xml">
  <!ENTITY commands		SYSTEM "commands.xml">
  <!ENTITY fdl-appendix		SYSTEM "fdl-appendix.xml">

  <!ENTITY eg			"e.&nbsp;g.">
]>

<!-- =============Document Header ============================= -->

<article id="index" lang="en">
  <articleinfo> 
    <title>Zapping &appversion; User Manual</title>       

    <copyright> 
      <year>2004</year>
      <year>2005</year>
      <holder>Michael H. Schimek</holder> 
    </copyright>

    <copyright> 
      <year>2001</year>
      <holder>Emacs documentation team (Regexp introduction)</holder>
    </copyright>

    <authorgroup> 
      <author> 
        <firstname>Michael</firstname>
        <surname>Schimek</surname>
        <othername role="mi">H</othername>
        <affiliation>
          <address>
            <email>mschimek@users.sourceforge.net</email>
          </address>
        </affiliation>
      </author>
    </authorgroup>

    <releaseinfo>This manual describes version &appversion; of Zapping.</releaseinfo>

    <legalnotice>
      <title>Feedback</title> 

      <para>To report a bug or make a suggestion regarding this application or this manual, visit the <ulink url="http://sourceforge.net/tracker/?group_id=2599">Zapping bug tracker</ulink> or mail us at <ulink url="mailto:zapping-misc@lists.sourceforge.net"> zapping-misc@lists.sourceforge.net</ulink>.</para>
    </legalnotice>

  </articleinfo>

  <indexterm zone="index">
    <primary>Zapping</primary>
  </indexterm>

<!-- ============= Document Body ============================= -->

  <sect1 id="zapping-introduction"> 
    <title>Introduction</title>

    <para>With the Zapping application you can watch TV, take
screenshots and record video and audio. Zapping has a deinterlacer and
a Teletext viewer built in and supports Closed Caption and Teletext
subtitles.</para>

    <para>This document describes version &appversion; of Zapping.</para>
  </sect1>

  <!-- Getting Started -->

  <sect1 id="zapping-getting-started"> 
    <title>Getting Started</title>

    <sect2 id="zapping-install">
      <title>Installation</title>

      <para>Which hardware is supported by Zapping?</para>
      <para>Zapping does not talk to hardware directly, it uses
drivers already installed on your computer. Hardware thus supported
includes <emphasis>analog</emphasis> TV cards, graphic cards with
video capture capability, both with and without tuner, and some USB
cameras.</para>

      <variablelist>
	<varlistentry>
	  <term>Video4Linux or Video4Linux2 kernel drivers</term>
	  <listitem>
	    <para>Zapping can capture video, VBI (Teletext and Closed
Caption) data and overlay video if this is supported by your driver.
For installation and configuration of the driver please consult V4L or
driver documentation.</para>
	    <para>When the driver and your TV card supports video
overlay the appearance can be improved by enabling the XFree86
V4L/XVideo interface driver. If it has not been done already, open the
file <filename>/etc/X11/XF86Config</filename> and add <userinput>Load
"v4l"</userinput> to the module section:</para>
	    <programlisting>
Section "Module"
        &hellip;
        Load  "v4l"
EndSection
</programlisting>
            <para>Alternatively Zapping can use the XFree86 DGA
extension. You may have to comment out this line:</para>
            <programlisting>
Section "Module"
        &hellip;
#      Option  "omit xfree86-dga"
EndSection
</programlisting>
            <para>Unfortunately on some graphics card the v4l module
and DGA do not work very well or at all when 3D graphics support
(OpenGL, DRI) is enabled.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>BKTR kernel driver (FreeBSD)</term>
	  <listitem>
	    <para>Zapping can capture video, VBI (Teletext and Closed
Caption) data and overlay video with this driver. For installation and
configuration of the driver please consult the FreeBSD
handbook.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>XVideo drivers</term>
	  <listitem>
	    <para>XVideo is an extension of the X Window system supporting video capture and output devices. With it, Zapping can display live video in a window. Video and VBI capturing is not possible with XVideo.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="zapping-start">
      <title>To Start Zapping</title>

      <para>You can start Zapping in the following ways:</para>
      <variablelist>
	<varlistentry>
	  <term><guimenu>Applications</guimenu> menu</term>
    	  <listitem>
    	    <para>Choose <menuchoice><guisubmenu>Sound and Video</guisubmenu>
		<guimenuitem>Zapping</guimenuitem></menuchoice>.</para>
          </listitem>
    	</varlistentry>
    	<varlistentry>
    	  <term>Command line</term>
    	  <listitem>
    	    <para>To start Zapping from a command line, type the following command, then press <keycap>Return</keycap>:</para>
            <para><command>zapping</command></para> 
          </listitem>
    	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="zapping-when-start">
      <title>When You Start Zapping</title>

      <para>When you start Zapping, the following window is displayed.</para>

      <figure id="zapping-figure"> 
	<title>Zapping window</title> 
	<screenshot>
	  <mediaobject> 
	    <imageobject>
	      <imagedata fileref="figures/zapping.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject>
	</screenshot>
      </figure>

      <para>The Zapping window contains a menu, toolbar and a context menu which opens when you click on the video with the right mouse button.</para>

      <figure id="zapping-context-figure">
	<title>Zapping Context Menu</title>
	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/zapping-context.png" format="PNG"/>
	    </imageobject>
	    <textobject>
	      <phrase>Context menu.</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </figure>
    </sect2>
  </sect1>

  <sect1 id="zapping-usage">
    <title>Usage</title>

    <sect2 id="zapping-video-modes">
      <title>Video Modes</title>

      <para>Zapping can work in windowed, fullscreen or background mode. In each mode it can show Teletext, capture images or it can overlay video. What is the difference between capture and overlay mode?</para>
      <para>In capture mode Zapping programs your TV card to store images in main memory. This permits screenshots, deinterlacing and video recording. It is also quite CPU intensive because to display video Zapping must copy the images to the X server which programs the graphics processor to convert the images from YUV to RGB format, scale them, and copy them into screen memory.</para>
      <para>In overlay mode the TV card stores the images directly in screen memory. This is a more efficient display method, but now Zapping cannot access the images. When you try to take a screenshot, activate deinterlacing or recording in this mode it will switch back to capture mode, if supported by your TV card.</para>
      <para>The available PCI bus bandwidth limits the image size in overlay mode. When the window or screen is larger than 768&times;576 pixels you will see a black border around the image. To avoid this Zapping can automatically <link linkend="zapping-settings-video-options">reduce the screen resolution</link> in fullscreen mode, or you can switch to capture mode. Capture mode is not limited if your graphics card supports hardware image scaling.</para>

      <para>To switch between modes choose the mode from the <menuchoice>
	  <guimenu>View</guimenu>
	</menuchoice> menu, or the context menu. To return from fullscreen or background mode to windowed press the <keycap>Esc</keycap> key.</para>
      <para>In windowed mode you can freely resize the video. You can either resize the window as usual by dragging its border, or choose a size from the context menu <menuchoice>
	  <guimenu>Appearance</guimenu>
	</menuchoice> submenu. This menu is editable, see the <link linkend="zapping-settings-video-options">preferences</link> section for details.</para>
    </sect2>

    <sect2 id="zapping-channels">
      <title>To Change Channels</title>

      <para>To change between TV channels you can choose from the <menuchoice>
	  <guimenu>Channels</guimenu>
	</menuchoice> main menu or the context menu. The menu also lists video inputs on the device and supported video standards. Note you can add composite video inputs to the channel list as well, see the <link linkend="zapping-channel-editor">Channel Editor</link> section for details.</para>
      <para>To change to the next or previous channel in the list click on the <guilabel>Ch. Up</guilabel> or <guilabel>Ch. Down</guilabel> button in the toolbar, or press the <keycap>Pg Up</keycap> or <keycap>Pg Dn</keycap> key.</para>
      <para>On the numeric keypad (if <keycap>NumLock</keycap> is activated) you can enter a channel number. Either the number of the RF channel, or a channel list number. This can be changed in the <link linkend="zapping-settings-main">preferences</link>.</para>
    </sect2>

    <sect2 id="zapping-controls">
      <title>Picture controls</title>

      <para>To change the picture brightness, contrast and other controls click on the <guilabel>Controls</guilabel> button in the toolbar. Control levels can be changed by keyboard too, as configured in <link linkend="zapping-settings-keyboard">preferences</link>.</para>
    </sect2>

    <sect2 id="zapping-volume">
      <title>Volume and Mute Functions</title>
      <para>You can change the audio volume or mute audio in the controls dialog, opened when you click on the <guilabel>Controls</guilabel> button in the toolbar.</para>
      <para>Further you can click on the <guilabel>Mute</guilabel> button in the toolbar or choose <menuchoice>
	  <guimenu>View</guimenu>
	  <guisubmenu>Mute</guisubmenu>
	</menuchoice>.</para>
      <para>You can also press <keycap>A</keycap> or the <keycap>Enter</keycap> key on the numeric keypad to mute or unmute, <keycap>+</keycap> or <keycap>-</keycap> to change the volume level.</para>
    </sect2>

    <sect2 id="zapping-caption">
      <title>Caption / Subtitles</title>

      <para>Caption is an aid for the hard of hearing while subtitles help viewers understand programs in foreign languages. Technically there is no difference, so we use these terms interchangeably in this document.</para>
      <para>Zapping supports Closed Caption and Teletext subtitles.
Closed Caption is common in the USA and can also be found on DVDs and
other media. Teletext subtitles are mainly broadcast in Europe.</para>
      <para>Zapping supports multiple languages. These are transmitted
on different Closed Caption "channels" or on different Teletext pages.
Whenever possible Zapping displays language names instead of channel
or page numbers.</para>
      <para>To enable subtitles choose the desired channel, page or
language from the context menu <menuchoice>
	  <guimenu>Subtitles</guimenu>
	</menuchoice> submenu. To disable subtitles choose
<menuchoice>
	  <guimenu>Subtitles</guimenu>
	  <guisubmenu>Disable</guisubmenu>
	</menuchoice>. You can also click on the
<guilabel>Subtitles</guilabel> button in the toolbar to enable or
disable subtitles.</para>
      <para>Closed Caption channels are always listed in the menu if
transmitted, Teletext subtitles only if the station transmits
subtitle links. To choose a Teletext subtitle page manually switch to
Teletext mode, go to the desired page and click on the
<guilabel>Subtitles</guilabel> button in the toolbar.</para>
      <para>When Zapping displays subtitles you can drag them to a
different position with the left mouse button. To resize subtitles
hold the <keycap>Shift</keycap> key down or drag with the middle mouse
button.</para>
      <para>Clicking on subtitles with the right mouse button opens a
context menu where you can disable the subtitles or choose another
language. With the <menuchoice>
	  <guimenu>Encoding</guimenu>
	</menuchoice> submenu you can override the character encoding
of Teletext subtitles, which is sometimes incorrectly
transmitted.</para>
    </sect2>

    <sect2 id="zapping-screenshot">
      <title>Take a screenshot</title>
      <para>To take a screenshot click on the
<guilabel>Screenshot</guilabel> button in the toolbar or press the
<keycap>S</keycap> key. A dialog will open where you can choose a file
name, image format and compression quality if applicable.</para>
      <para>The deinterlace option can remove interlace artefacts on
the fly. It makes no sense to deinterlace scaled images, so the option
is only available if the image height is 480 or 576 pixels. At your
discretion screenshots may or may not contain the displayed
subtitles.</para>
      <para>Screenshots are only possible if your TV card and its
driver supports video capturing.</para>
    </sect2>

    <sect2 id="zapping-record">
      <title>Record video and audio</title>
      <para>To record video and/or audio click on the <guilabel>Record</guilabel> button in the toolbar or press the <keycap>R</keycap> key. A dialog will open where you can choose a file name and format. Click on the <guilabel>Record</guilabel> button in the dialog to start recording, on the <guilabel>Stop</guilabel> button to stop.</para>
      <para>File formats can be configured in <link linkend="zapping-settings-recording">preferences</link>. You can create different configurations and name them as desired.</para>
      <para>Video recording is only possible if your TV card and its driver supports video capturing in realtime. Video compression hardware is not yet supported.</para>
      <para>Currently recording is not supported on FreeBSD.</para>
    </sect2>

    <sect2 id="zapping-remote">
      <title>Using a Remote Control</title>

      <para>Zapping supports the LIRC (Linux Infrared Remote Control) infrastructure. Visit <ulink url="http://www.lirc.org">http://www.lirc.org</ulink> for more information about LIRC.</para>
      <para>To use LIRC you must create a <filename>.lircrc</filename> file in your home directory. For each remote control button add an entry like these:</para><programlisting>
        begin
                prog   = zapping_lirc
                button = VOL_UP
                config = zapping.volume_incr(+5)
        end

        begin
                prog   = zapping_lirc
                button = 0
                config = SETCHANNEL 0
        end

        begin
                prog   = zapping_lirc
                button = 1
                config = SETCHANNEL 1
        end

        begin
                prog   = zapping_lirc
                button = 9
                config = SETCHANNEL 9
        end
</programlisting>
      <variablelist>
	<varlistentry>
	  <term>prog</term>
	  <listitem><para>is the program interpreting the command and must be <userinput>zapping_lirc</userinput></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>button</term>
	  <listitem><para>is the name of the remote control button. Presumably with LIRC you installed <filename>/etc/lircd.conf</filename>, this file lists all available buttons.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>config</term>
	  <listitem><para>is a Zapping command. Valid commands are listed in the <link linkend="zapping-commands-lirc">Commands</link> section.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>Suppose your remote control has a <guilabel>TV/RADIO</guilabel> button and you want to switch between two layers of commands, much like <keycap>Shift Lock</keycap> switches between lower and upper case characters.</para>
      <para>This can be accomplished by embracing the entries above within a zapping_lirc section, and programming the <guilabel>TV/RADIO</guilabel> button to enable this section, "switch to this mode" in LIRC speak.</para><programlisting>
begin zapping_lirc
        begin
                button = TV/RADIO
                mode   = radio
        end

        Zapping entries &hellip;
end zapping_lirc

begin radio
        begin
                button = TV/RADIO
                mode   = zapping_lirc
        end

        Other entries &hellip;
end radio

Mode-independend entries &hellip;
</programlisting>
      <para>Which mode will be initially selected? Well, none. But when you start Zapping it automatically switches to zapping_lirc mode, if such a section exists.</para>
      <para>For further instructions please see the LIRC documentation.</para>
    </sect2>

  </sect1>

  &settings;
  &channel-editor;
  &zapzilla;
  &commands;

  <sect1 id="zapping-about"> 
    <title>About Zapping</title> 

    <para>Zapping was written by Iñaki García Etxebarria, Michael H. Schimek and many contributors. Visit our web page at <ulink url="http://zapping.sourceforge.net" type="http"> http://zapping.sourceforge.net</ulink>.</para>
    <para>To report a bug or make a suggestion regarding this application or this manual, visit the <ulink url="http://sourceforge.net/tracker/?group_id=2599">Zapping bug tracker</ulink> or mail us at <ulink url="mailto:zapping-misc@lists.sourceforge.net"> zapping-misc@lists.sourceforge.net</ulink>.</para>
    <para>This program is distributed under the terms of the <ulink url="ghelp:gpl" type="help">GNU General Public License</ulink> as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found in the file COPYING included with the source code of this program.</para>
  </sect1>

  &fdl-appendix;

</article>

<!--
Local Variables:
mode: sgml
coding: utf-8
comment-auto-fill-only-comments: t
indent-tabs-mode: nil
End:
-->