
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 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 informartions" 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:
 - the insmod arguments for the modules
 - the kernel messages printed by bttv while loading.
 - have you tried the version which is bundled with xawtv?

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

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.

If it does'nt work, try

	$ ./configure --disable-kradio && make

kradio sometimes causes some trouble becauce it is a KDE application and
needs KDE, Qt (therefore moc) and a C++ compiler (all other applications
are plain C).

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

	# make install

There are precompiled binaries (i386, libc6) 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
----

required:
    stable kernels: 2.0.34     or newer
    development:    2.2.0-pre6 or newer

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
at least "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 (/dev/video, ...) for the driver.

To autoload the modules, stick something like this into
/etc/modules.conf:

# TV
alias   char-major-81   bttv
pre-install bttv        modprobe -k msp3400; modprobe -k tuner
options bttv            radio=0,1 vidmem=0xff0
options tuner           type=5

Again: this is for _my_ setup, you probably have to adjust the module
parameters.


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


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.


streamer
--------

Command line tool for streaming capture (single frames work too).
Try the '-h' switch 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...

It scans the devices /dev/mixer[0123]


record
------

records *.wav files.  See "record -h" for more info.  Has a input level
meter, which might be useful for sound trouble shooting.


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.

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 for config file handling.

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 for this.


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.

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.

There is a new videotext application: alevt.  Your friendly sunsite
mirror has it.  Check the freshmeat (http://freshmeat.net) application
index for details.


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).


resources
=========

http://www.in-berlin.de/User/kraxel/xawtv.html		- 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
http://FreeTV.Notrix.de


Have fun!

  Gerd

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