
small is beautiful
==================

This is a _simple_ xaw-based TV Program which uses the bttv driver or
video4linux (included in 2.1.x).  Copy Policy is GNU GPL.


before sending me email...
==========================

If you are upgrading from 2.x to 3.x, read the UPDATE_TO_v3.0
file.  There are a few incompatible changes you have to take care
of.

READ THE F*** MANUAL FIRST (this README file, Trouble-Shooting file,
xawtv man page, bttv driver documentation, the Sound-FAQ)

If you have problems after upgrading, please check the ChangeLog for
hints first.  Looking into the ChangeLog is a good idea in general,
becauce it is updated for every release, the other files are updated
less freqently...

For problem/bug reports:

 * emails with images attached will to to /dev/null.
 * emails with the word "nagra" or "premiere" will go to /dev/null.
 * emails with questions answered in the documentation will go to
   /dev/null.
 * emails which don't have any useful informations (like "xawtv
   does'nt work, please help me") will go to /dev/null.

"useful informations" includes at least:
 - xawtv version
 - kernel version
 - driver version
 - which grabber board
 - which TV norms are used in your country.
 - if xawtv prints errors, include these too.
 - don't forget a description of your problem :-)

If you are using bttv as driver:
 - the insmod arguments for the modules
 - the kernel messages printed by bttv while loading.

If you are _really_sure_ some information is'nt important for your
problem, you can skip it.  But if in doubt, better include it...


For patches/changes:
 * Please add a comment what is changed and and why you changed it.
 * Please send unified diffs ("diff -u") against the latest version.
 * Please don't reformat my source code.


compile & install
=================

A simple

	$ make

should compile xawtv, v4l-conf, maybe kradio and a few other
utilities.  You can install the programs (as root) with:

	# make install

If you want build RPMs:  No problem, just run

	$ rpm -ta xawtv-3.xx.tar.gz

and install them the usual way with "rpm -i".


usage
=====

bttv
----

bttv is'nt bundled with xawtv any more.  You can get my current bttv
code as separate tar file from http://www.in-berlin.de/User/kraxel/v4l/
Number scheme is Ralph's version it is based on plus a small letter
(i.e. bttv-0.6.3e for example).


v4l-conf
--------

v4l-conf is a small tool which tells video4linux about the current
video mode (size and color depth).  This requires root priviliges,
becauce it is easy to crash the box by passing bogous values there.
It requires the X-Server with DGA support up and running or a
framebuffer device.  It is a temporary hack, this problem will be
solved in a better way with a X11 extention.  The XFree86 snapshots
(3.9.x) already have some working code.

Try "v4l-conf -h" for a short description.  It is installed suid-root,
and xawtv runs it at startup.  Should work out-of-the-box without
extra configuration.  Normally you should'nt need to worry about it,
but for debugging it is handy do run it from the shell and check the
output.


xawtv
-----

There is a man page now, read it.  Don't expect you can use xawtv
without reading the documentation at least once.  You are lost if you
don't know the keyboard shortcuts,  xawtv is'nt a mouse-only program.

xawtv will not work without the app-defaults.  If you want to try
xawtv without installing it, use this...

	$ XUSERFILESEARCHPATH=./%N.ad
	$ export XUSERFILESEARCHPATH
	$ ./xawtv

...to make sure xawtv finds the application defaults (the Xawtv.ad
file).  If v4l-conf is'nt installed too, you have to run it once
(as root) before starting xawtv.


xawtv-remote
------------

remote control for xawtv.  Takes commands for xawtv as command line
arguments.  Check 'xawtv-remote -h' for details.

ObSecurity:  This uses X Properties, everyone who is allowed to connect
to your X11 Display can control xawtv.

There is a GUI (Qt) version at:
http://www.ben2.ucla.edu/~wtho/xawtv-qremote/xawtv-qremote-0.01.tar.gz


fbtv
----

TV program for the linux console.  Runs on top of a framebuffer
device, tested with vesafb (2.1.109+) so far.  Check out man-page and
source code for details.


v4lctl
------

This tool allows to control a v4l device from the command line.  Check
the man-page for details.


streamer
--------

Command line tool for streaming capture (single frames work too).
Try the '-h' switch for a description.


radio
-----

You have to load the driver using "insmod bttv radio=1" for radio
support.  The MAKEDEV script should create the required /dev/radio*
devices.

radio is a console application (curses).  up/down tune, 'q' quits,
the function keys recall the programmed stations.  radio reads the
kradio config file.  You can't configure anything with radio, you'll
have to use kradio or vi for this.  The config file format is
documented in the man page.

kradio (my KDE radio app) is'nt included any more, it is available as
separate tarball now.


videotext / teletext
--------------------

There is a new videotext application for bttv: alevt.  Your friendly
sunsite mirror has it.

Ralph has written a software decoder for teletext.  You can download
it from his web-page.  There is a program called videoteXt which can
be used to view the teletext pages.  A link to this package is on
Ralphs page too.

In the vtx subdirectory is a simple vtx2ascii converter, build quick&diry
out of the videoteXt sources.  Can output ascii (with and without
ansi-colors) and html.  A perl-cgi is included too.


webcam
------

This is a webcam tool.  Captures a image, annotates with a text +
current time and uploads it to the webserver using ftp in an endless
loop.  Needs the ftp utility.  Should survive dropped ftp-connections
(webserver reboot) without problems.

It is'nt compiled by default, you can compile it with "make webcam".
All config options are compile time options, check out the #defines in
webcam.c.  For normal operation, webcam is simply started without
arguments (and it should work until someone kills it).  If the number
of arguments is non-zero, webcam prints the complete communication
with the ftp utility to stderr (for debugging purpurses).


perl
----

Hint for all perl users/hackers:  There is a Video::Capture::V4l module
available at CPAN.  It can do capture, vbi decoding, and it comes with a
nifty tool to do a channel scan (decodes the station ID from vbi).


resources
=========

http://www.in-berlin.de/User/kraxel/xawtv.html		- xawtv	[me]
http://user.exit.de/froese/				- alevt	[Edgar]
http://www.thp.uni-koeln.de/~rjkm/linux/bttv.html	- bttv	[Ralph]
http://www.ee.up.ac.za/~justin/v4l2/			- bttv2 [Justin]
http://roadrunner.swansea.uk.linux.org/v4l.shtml	- v4l	[Alan]
http://millennium.diads.com/bdirks/v4l2.htm		- v4l2	[Bill]
http://www.tk.uni-linz.ac.at/~simon/private/i2c/	- i2c	[Simon]
http://www-nrg.ee.lbl.gov/vic/				- vic
http://FreeTV.Notrix.de


Have fun!

  Gerd

--
Gerd Knorr <kraxel@goldbach.in-berlin.de>
