Zapping - A GNOME TV viewer
---------------------------
	OK, here it is.
	Some time ago I bought a TV card for my computer. In my Linux
box there were only a few TV viewing programs, and none of them for
Gnome. So I built a TV viewer following V4L2 spec (not compiled into
the Kernel by default) from scratch, but trying to make it as complete
as possible. This is the latest version of that software.

INSTALLING
----------
	To install this package just run as a normal user:
./configure && make
	And as root:
make install
	Type './configure --help' for extra options you can give to
the configure script.

PROGRAM INFO
------------
	* XFree notes:
	In releases of XFree prior to 4.0, if you capture with a
screen depth over 16bpp, CPU usage jumps to 100%. This is actually a
XFree thing, and it is solved with XFree 4.0. But fullscreen mode
won't work with XF4.0, because DGA doesn't work by default with some
drivers. This is usually fixed with XF4.0.1 (at least it fixed it for me).
	The fullscreen mode uses framebuffer access. For using it,
root privileges are needed. I created a small SUID program that sets
up everything and returns. There is a potential security flaw here (i
tried to make it secure, but don't trust it very much), so if you
really care about security, you may:
	a) Uninstall the program (check its location with 
		'which zapping_setup_fb').
	    You won't have fullscreen mode then, but there would be no
	    security flaw.
	b) Check the suid's sources and locate the security flaws.
	   Drop me a line and in a couple of hours since i read the
	   message it will be fixed (this is the preferred method ;-)

KEYS
----

Zapping maintains four tables of keys: The Gnome accelerators
(Ctrl+some) you see in menus, some built-in keys, those you can
assign functions in the preferences keyboard dialog, and those
bound to TV channels (to switch to said channel, say, using F1
to F8) in the channel dialog.

When you hit a key Zapping looks it up in these tables, in this
order. Because the other keys are listed in the GUI, here just a
summary of the built-in keys:

In the main window you can type a channel number on the numeric
keypad. The number refers to channel memory (European style)
or is interpreted as the RF channel name (US style) depending
on the respective Preferences / General / Main Window option.
Use the decimal point key to enter channel prefixes (T, S, E,
etc). Don't forget to activate NumLock. :-)

In a Teletext window you can use the main or keypad number
keys to enter page numbers.

COMMANDS
--------

Along with the keyboard preferences comes a new set of commands
for Zapping. Note these commands apply *only* to these keys,
the legacy commands are still in place will be merged in at a
later date.

A command consists of the command name and parameters separated
by spaces. Example: 'ttx_open_new 100'. To pass parameters
with spaces put them in double quotes "like this". A backslash \
overrides the special meaning of the following character like \"
a literal quote, \\ the backslash itself. The semicolon ; separates
commands.

[] = optional argument

channel_up
- Selects next (higher number) channel in the channel list.

channel_down
- Selects previous (lower number) channel in the channel list.

set_channel number
- Selects this channel from the channel list. You can see
  the number in the channel dialog, in the first column of
  the channel table.

lookup_channel name
- Selects this channel by station name. When the name does not
  match, it searches the current frequency table for a channel
  name (like "12", "E3", etc).

mute [whence]
- Mutes audio: 1 - silence, 0 - sound, none - toggle.

volume_incr [number]
- Preliminary command to change the audio recording volume,
  specifically of the recording line selected in Preferences
  / General / Audio of the OSS mixer /dev/mixer. The number
  is a percentage (-100 to +100) added to the current volume.

ttx_open_new [page number [subpage number]]
- Opens a new Teletext window, loads the requested page.

ttx_page_incr [number]
- Display a different Teletext page by adding number to the
  current page number. By default number is +1, can be a
  negative value as well.

ttx_subpage_incr [number]
- Same as ttx_page_incr, but this keeps the page number
  and modifies the subpage number.

ttx_home
- Display the Teletext index page (usually page 100).

ttx_hold [whence]
- Disable rolling of Teletext subpages in the current
  window: 1 - disable, 0 - enable, none - toggle.

ttx_reveal [whence]
- Display hidden text on a Teletext page: 1 - reveal,
  0 - hide, none - toggle.

screenshot [format]
- Open screenshot dialog. If given preselect the
  image format as ppm or jpeg.

quickshot [format]
- Same as screenshot, but this also hits OK for you.

FEEDBACK and TROUBLESHOOTING
----------------------------
	Please read the included BUGS file. If your bug is there, i
probably know about it, but feedback on them is very appreciated. If
they are still there it is because i don't know how to fix them or i
cannot reproduce them, so i need your help.
	Disabling things can be useful, run 'zapping --help' to see
what can be disabled (the "--no-" options at the end).
I need feedback specially on these bugs:
*) Overlay image through all screen:
	- Use the command line --bpp option giving the real X
	server depth. Usually 24 or 32 if you have this problem.

*) The program just hangs after showing the main window.
	I have experienced this one myself with a 2.4.0test8
	kernel, and appearently it gets fixed in the 0.5.4 release. I
	would really appreciate some feedback on this one.

*) Teletext just shows loading..., no page ever loaded
	a) you aren't getting a proper TTX signal. This can be due
	to a very bad reception of simply no signal broadcast.
	b) This can also be due to a very old V4L1 driver or a V4L2
	driver not compliant with the latest release of the spec.

*) The camera/dvd player/whatever connected to Composite uses
NTSC/SECAM/..., and the image appears horribly distorted/colorless/...
	That's because PAL is being used for those inputs. Use the
	--tunerless-norm option to set the norm for those inputs. You
	might switch to V4L2, since it doesn't have this limitation.

*) It crashes when loading the program, complaining about a Gdk-Error,
request_code 14x, but it didn't happen before (Zapping < 0.5.8).
	That appears to be a bug with XV support (either the X driver
	or Zapping itself). The --no-xv option might help, but please
	contact me (garetxe@users.sourceforge.net), maybe i can fix
	the bug.

*) Overlay just works as root, cannot be started as user.
	Probably you are being hit by a PAM bug. Upgrading to 0.72
	fixed it for me, if that doesn't work you can try using the
	--disable-pam switch to ./configure
	./configure --disable-pam
	and then recompile, reinstall.

USEFUL ADDRESSES
----------------
http://www.thedirks.org/v4l2/
	Video for Linux 2 home page. There are links to some other
	pages regarding the V4L2 project.
http://www.strusel007.de/linux/bttv/index.html
	Video for Linux home page. Actually the bttv page.
http://lecker.essen.de/~froese
	AleVT home page. Probably the second best ;-)
	Teletext decoder around.
http://www.gnome.org
	The home page of the GNOME community. Lots of info about
	projects and programming.
http://www.gtk.org
	The toolkit used to build Gnome and this program.
http://rpmfind.net/linux/RPM/libxml.html
	Libxml, needed for compiling Zapping (rpm package).
http://www.megaloman.com/~hany/RPM/doors2.3/libglade-0.12-1.i586.html
	Libglade, the library used to build the interface (mdk package).
http://zapping.sourceforge.net
	I haven't the slightest idea of what's here, sorry. A strange
	man with a strange face told me to put this here. Go figure.

SUPPORT
-------

The Zapping homepage is http://zapping.sourceforge.net/
Sourceforge project page is http://sourceforge.net/projects/zapping/

Let us know about your ideas, questions and bugs you found
using the tracking system https://sourceforge.net/tracker/?group_id=2599
or send a message to the Zapping mailing list
zapping-misc@lists.sourceforge.net, registration is not necessary.

	thanks and enjoy the TV (as difficult as that might seem),
	Iaki
