
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
=======================

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

For Hauppauge boards:  Make sure you have enabled the msp reset code in
the driver Makefile.

If the image is spread across the screen (and not within the xawtv
window) in TrueColor mode, try the '-b' option.  This might be required
to tell xawtv whenever the X-Server runs the board in packed pixel mode
(24 bit/pixel) or not (32 bit/pixel).  If in doubt, just try both.  One
should work...

	xawtv seems to become quite popular :-)
	Unfortunaly, this increases my email load :-(

	My spare time is limited.
	I'll ignore emails with FAQ's.
	I'll ignore emails without informations
		("does'nt work, please help").
	I'm not going to provide newbie support.

Remember that there are various TV video/audio standards all over the
world.  I can't test them all myself.  I don't even know them all
exactly.

For xawtv/bttv bug reports:
 * Include informations about your TV system.
 * Please cut & paste error messages (I hate "says something
   like...").
 * If there are error messages in the kernel log, or you suspect a
   driver bug, include the kernel messages.
 * Include your bttv version.
 * If you don't use the version included with xawtv, please check
   it out.  

Sound (msp3400 kernel module) trouble:
 * please make sure it is'nt a soundcard problem (connect a speaker
   directly to the Grabber Board to check)
 * "insmod msp3400 debug=1", and include the kernel messages.
 * Include informations about your TV system, especially for sound
   (NICAM, ...).

For changes:
 * Please add a comment what is changed and and why you changed it.
 * Please send unified diffs ("diff -u") against the latest version.


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

There is (maybe modified) bttv driver in the bttv subdirectory.  Only
the driver and doc subdirectories are included, not the whole bttv
package.  If you use the bttv for the first time, I recommend to get
the whole bttv package from Ralph's page (see below) and check out the
documentation.  Some (very limited) informations can be found in the
bttv/MODULES file.

$ make

should compile xawtv, v4l-conf, maybe kradio and a few other
utilities.

You can install xawtv, v4l-conf and kradio (as root) with:

# make install


There are precompiled binaries (i386, libc5) in the package, but these
have to be installed by hand.  Don't forget the app-defaults for xawtv
and the X11 font when doing so.  v4l-conf must be installed suid-root.


usage
=====

bttv
----

You need configured kernel sources to compile the bttv driver.  The
driver uses some Makefile magic to compile the modules with your
kernel's configuration (wrt. module-versions, SMP, ...).  If you
already have compiled the kernel at least once, you probably don't
have do worry about this.  If not, go to /usr/src/linux and run
"make config".  Even better, compile your own kernel, you'll never
become a real hacker else ;-)

Of cource you have to load the modules as very first thing.  There is
a script called "update" in the bttv/drivers directory.  I use this
one to load a new version while doing driver hacking.  You can use it
too, but check the module arguments before.  They work for my setup,
and probably do *not* for yours.  The module arguments are documented
in bttv/driver/MODULES.  The bttv/driver/MAKEDEV script creates the
special files for the driver.


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 up and running.  It is a temporary hack, this
problem probably will be solved in a better way later on (Alan plans
to write a X-Server extention).  Try "v4l-conf -h" for a short
description.

It is installed suid-root now, and xawtv runs it at startup.  Should
work out-of-the-box without extra configuration.


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, type...

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

...to make sure xawtv finds the application defaults (the Xawtv.ad
file).


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.


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.


set-tv
------

Simple command line tuner.  Reads like xawtv the config file $HOME/.xawtv.
Expects a channel name on the command line.  Assuming you have a station
named [ZDF] in your $HOME/.xawtv file, "set-tv zdf" will tune in the
channel defined there.  That way you can tune in a station to grab
teletext (or whatever) without starting up X11.

It prints some useless messages about video resolution due to the fact that
it shares alot of code with xawtv, maybe I fix this later.


grab-one
--------

Command line tool for grabbing single pictures (full-size, PPM or raw).
Try "grab-one -h" for a description.


dump-mixers
-----------

Just does what the name suggests:  It simply dumps the current mixer
settings to stdout.  I used it to debug the msp3400 module, maybe
someone finds this useful...


vic
---

The grabber-bttv-0.5.6.cc file is a grabber driver for vic, works with
plain bttv-0.5.6.  Up to 12 fps.

There is newer version, grabber-video4linux.cc.  This one runs with newer
bttv versions (0.5.7/8) and the current kernel code.

Both versions are tested only with PAL.  The "large" picture size probably
doest'nt work with NTSC.  

If you plan to compile vic:  It is'nt trivial, you should have some
basic knowledge about C and writing/editing Makefiles. 


radio & kradio
--------------

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 quite simple command line radio application.  It just
promps for a (FM) frequency.  Give him a new frequency to change the
station, just hit enter to exit the program.  You can pass the initial
frequency on the command line.

kradio is a more comfortable KDE application.  There is a font in the
font subdirectory, it is required for kradio (for a cool LED-Style
display :-).  Make sure the KDEDIR and QTDIR environment variables are
set correctly.
BTW: kradio should run happily with any window manager.  The only KDE
stuff needed is the kdelibs package becauce kradio uses some of the
KDE functions.


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

Ralph has written a software decoder for teletext.  You can donwload
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.


resources
=========

http://www.cs.tu-berlin.de/~kraxel/linux/#xawtv		- xawtv       [me]
http://www.thp.uni-koeln.de/~rjkm/linux/bttv.html	- bttv driver [Ralph]
http://roadrunner.swansea.uk.linux.org/v4l.shtml	- video4linux [Alan]
http://www.tk.uni-linz.ac.at/~simon/private/i2c/	- i2c bits    [Simon]
http://www-nrg.ee.lbl.gov/vic/				- vic
http://www.kde.org					- KDE


Have fun!

  Gerd

--
Gerd Knorr <kraxel@cs.tu-berlin.de>
