Documentation overview
======================

README		[this file] gives a overview over the package.
		Build instructions, short overview over every
		program, some maybe useful URL's.

man pages	For most programs a manual page is available.

README.xfree4	Some notes about XFree86 4.x and the Xvideo
		extention.

README.recording If you want record videos, have a look at this
		file.  It also has some notes about how to process /
		playback the files recorded by xawtv/streamer.

README.network	How to stream video/audio over the net. Pointers to
		other software for the most part.

README.lirc	Some hints how make lirc work with xawtv.

README.bttv	Some hints to get bttv going, also lists some
		known problems.

UPDATE_TO_v3.0	Some hints for upgrading from 2.x to 3.x (config
		file syntax changes, ...)


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

IMPORTANT:  Don't send me mails with images attached unless I ask you
to do so.  Mails with images attached will go to /dev/null unseen, you
will never ever see an answer for these.

If you have problems after upgrading, please check the ChangeLog for
hints first.  Looking into the ChangeLog is a good idea in general,
because it is updated for every release, the other files are updated
less frequently and might be a bit outdated.

For problem/bug reports:

 * emails with questions answered in the documentation will go to
   /dev/null.
 * emails which don't have any useful informations (like "xawtv
   doesn't work, please help me") will go to /dev/null.

"useful information" includes at least:
 - xawtv version
 - kernel version
 - which driver (+ version if you know)
 - which hardware (although I probably can help with bttv
   driver problems only).
 - which TV norms are used in your country.
 - if xawtv prints errors, include these too (cut+paste)
 - 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 isn't important for your
problem, you can skip it.  But if in doubt, better include it...


For patches/changes:

 * Please add a comment on what is changed and why you changed it.
 * Please send unified diffs ("diff -u") against the latest version.
 * Please don't reformat my source code.
 * Complete patches have better chances to go in.  Quick+dirty hacks
   which need cleanups and lack documentation updates are less likely
   to go in simply because I need more time to deal with them.


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

The commands

	$ ./configure [ options ]
	$ make

should compile xawtv, v4l-conf, fbtv and a few other utilities.  You can
also simply type "make" if you don't want to pass any options to
configure.

If it fails, check that all required packages are installed.  Note that
the *-devel packages are also required to compile stuff, i.e. you need
both libjpeg and libjpeg-devel for example.

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 isn't bundled with xawtv any more.  You can the latest version
from http://bytesex.org/bttv/.  If you are using kernel 2.4.x, it is
very unlikely that you need an update, the bttv driver in 2.4.x is
updated in regular intervals.


v4l-conf
--------

v4l-conf is a small tool which tells video4linux about the current
video mode (size and color depth).  This requires root privileges,
because it is easy to crash the box by passing bogus 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.  See README.xfree4
for details.

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 shouldn't 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 isn't 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 isn't installed too, you have to run it once
(as root) before starting xawtv.


motv
----

That's basically xawtv with better (IMO), motif-based GUI.  Feature set
is very close to xawtv, they share a lot of code (basically everything
but the athena/motif GUI code).

motv uses Motif 2.x features (utm, render tables).  This means you
need openmotif, lesstif does *not* work.


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

remote control for xawtv.  Works with motv too.  Takes commands for
xawtv as command line arguments.  Check 'xawtv-remote -h' for details.
A man-page exists too.

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.  Check out man-page and source code for details.


ttv
---

aa-lib based TV app which renders the TV image on any text terminal.


scantv
------

scans for tv stations and writes a initial config file for xawtv and
motv.


v4lctl
------

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


streamer
--------

Command line tool for streaming capture, including audio.  Single
frames work too.  Try the '-h' switch for a description.  A (short)
man page is available too.


pia
---

simple movie player, should play every movie file (mov+avi) recorded
by streamer, xawtv and motv.


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) isn't included any more, it is available as
separate tarball now.


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

alevt is _the_ videotext application for bttv.  URL below.

A http server for videotext called 'alevtd' is in the vbistuff
subdirectory.  Recent xawtv version also come with mtt, which is a
interactive videotext application for X11 (Motif) and console.


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 has a man-page...


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://bytesex.org/xawtv/				- xawtv	[me]
http://bytesex.org/bttv/				- bttv	[me]
http://lecker.essen.de/~froese/				- alevt	[Edgar]
http://bttv-v4l2.sourceforge.net/			- bttv2 [Justin]
http://roadrunner.swansea.uk.linux.org/v4l.shtml	- v4l	[Alan]
http://www.thedirks.org/v4l2/				- v4l2	[Bill]
http://www.tk.uni-linz.ac.at/~simon/private/i2c/	- i2c	[Simon]
http://www-mice.cs.ucl.ac.uk/multimedia/software/vic/	- vic

Have fun!

  Gerd

--
Gerd Knorr <kraxel@bytesex.org>

Some hints to get the bttv driver up and running
================================================

general hints
-------------

(1) Make sure if your board is recognized correctly. The bttv driver
    should print a line like this one (Use the 'dmesg' command to see
    the kernel messages):

	bttv0: model: BT848(Hauppauge old)

    If your card isn't autodetected correctly, you have to specify the
    board type as insmod argument (card=n).  You might also have to
    specify tuner=x and pll=x.
    Check the driver documentation for details and a list of supported
    cards.  The standard kernel has the bttv documentation in the
    Documentation/video4linux/bttv directory.

(2) If you are using a vanilla 2.2.x kernel kernel, it is worth trying
    to upgrade as the very first step.  Either download and build bttv
    0.7.x for your 2.2.x kernel, or upgrade to 2.4.x which includes
    the 0.7.x driver already.
    bttv 0.7.x knows a lot more cards than the 2.2.x kernel driver, the
    autodetect is much improved and a number of known problems is
    fixed.

(3) If you have problems with xawtv, you should open a xterm (or
    whatever your favorite terminal app is) and start xawtv from
    there. This way you'll see any error messages xawtv might print on
    stderr which should help to find the source of the problems.

(4) If something broke after an update, have a look at the changelog.
    It might be mentioned there.


common problems
---------------

?: I have a black screen in overlay mode
!: The driver was not initialized correctly, v4l-conf (or the
   X-Server) has to configure the bttv driver with the current video
   mode and framebuffer address first.  Check if v4l-conf is installed
   suid root, it needs root priviliges to do this.  You can also start
   v4l-conf from a terminal and check the messages it prints.

?: I have a blue screen.
!: Good, the overlay is working.  A blue screen is what you get if the
   grabber chip has no input signal.  You are probably using the wrong
   video source, pick another.  Also happens sometimes if the tuner
   type is wrong, check the driver configuration.

?: I have a noisy screen and/or can't tune (some) stations.
!: Most likely the tuner types is wrong, check the driver configuration.
   It's no problem to do trial-and-error here.

?: The video is outside the window and spread in thin lines over the
   screen.
!: xawtv / v4l-conf didn't autodetect the color depth for your screen
   correctly.  You can fix that with xawtv's -bpp switch.

?: Only the left part of the window is updated, the right one is updated
   never / sometimes / only if the window is small.
!: Your graphics card and/or motherboard can't deal with the data rate
   going over the PCI bus, leading to canceled PCI transfers.  Reduce
   the color depth, with 16 bpp instead of 32 bpp should work much
   better.

?: I get no sound.
!: (a) If your TV-Card is connected to the sound card's line in with a
       short cable: Make sure the sound driver is loaded, sound cards
       are usually quiet until initialized by the driver.  Also check
       the mixer settings.
   (b) Double-check the card type is correct (see above).
   (c) If there is still no go, have a look at the Sound-FAQ in the
       bttv documentation.


hardware specific problems
--------------------------

 * bttv + DRI seem not to play nicely together with some cards (ATI
   Rage128).  The linux box just freezes.  Don't know why.  Suspect
   it's either a hardware problem or a bug somewhere in DRI (either
   kernel or xfree86).  The only workaround I know of is to turn off
   DRI.

 * Some motherboard chipsets have PCI bugs, especially with PCI-PCI
   transfers which are used for video overlay.  The bt848/878 chips
   have some bug compatibility options, which can be enabled to
   workaround these problems.  Have a look at the triton1 and vsfx
   insmod options.  For some known-buggy chipsets these are enabled
   automagically.

 * Sometimes IRQ sharing causes trouble.  It works most of the time,
   but in combination with some hardware and/or drivers it doesn't work.
   Especially graphic cards are known to cause trouble due to the lack
   of a IRQ handler.  Try disabling the VGA IRQ in the BIOS.  Try moving
   cards to another PCI slot.  Your motherboard manual should tell you
   which PCI slots share IRQ's.

Starting with version 3.71 xawtv + friends do not need a ~/.lircrc
config file any more.  There is a new config mechanism to map input
events (lirc, joystick, keyboard) into xawtv commands which is called
"eventmap".  Check the xawtvrc manpage ([eventmap] section) for
details.  There also is an default configuration now, so lirc support
should simply work out-of-the-box.

If there is no ~/.lircrc config file present, xawtv will generate
lirc-key-* events for every key pressed on the IR remote.

If ~/.lircrc is present, xawtv will still use it.  As strings for
"config" are the usual xawtv commands (the traditional way to
configure lirc support, see "man xawtv-remote") and the keyword
"eventmap" allowed.  Specifying "eventmap" will make xawtv simply
generate lirc-key-* events.

The main difference between using no config file at all and one with
"config = eventmap" is that the later allows you to filter the
keypresses depending on the current mode.  The simpliest way to make
xawtv use the default eventmap configuration, but respond to key
presses in xawtv mode only looks like this:

begin xawtv
	begin
		prog = xawtv
		config = eventmap
	end
end xawtv

You probably need this if you are going to control multiple
applications with your IR remote, check out the lirc documentation for
details.

Have fun,

  Gerd

How send audio/video data over the net?
=======================================


Just some pointers where to look.  I haven't tried everything myself.


still images (webcam)
---------------------

You can use the xawtv's webcam utility (in the webcam subdirectory) to
capture single frames and upload them to a (web-)server using ftp.

There are plenty of other tools for that purpose, http://freshmeat.net
has a list.


both audio and video
--------------------

You can use video conferencing tools, see http://www.openh323.org.  That
should even interoperate with M$ Netmeeting.  I've heard there is a
project named "gnomemeeting" ...

You might want to have a look at videolan (http://www.videolan.org).

Using the mbone tools (i.e. vic for video, vat or rat for audio) works
too,  see http://www-mice.cs.ucl.ac.uk/multimedia/software/
Drawback is that these two work independent of each other, that's why
there is no way to make audio and video sync properly.


video only
----------

xawtv works with a remote display.  Eats plenty of network bandwith as
the X11 protocol is not optimized for streaming video.  Can be used to
max-out ATM cards.  Don't even think about it with something slower
than Ethernet.


audio only
----------

Use some network sound daemon, esound for example:
sox -w -c 2 -r 44100 -t ossdsp /dev/dsp -t raw - | esdcat -r 44100

Check out http://freshmeat.net, IIRC there are some tools to multicast
audio data.

Recording movies
================


Audio
=====

If you don't get sound when recording avi movies, double-check the
mixer settings first.  The record source defaults to micro on many
linux sound drivers, you probably have to change this to line-in with
one of the available mixer tools.  Some sound cards have a separate
input gain control which needs to be set to some approximate value.
Also keep in mind that ALSA has all mixer controls at 0 (i.e. muted)
by default.

/me uses kmix (because it doesn't need much space on the screen).
The inputs where the sound cards record from have a red background
color.  With the right mouse botton you'll get a menu where you can
change the settings.  FreeBSD has a aumix version with X11 GUI in
the ports collection which is very nice too (aumix-gtk in debian).

If you want to see something while playing with the mixer settings you
can use the record utility (ncurses terminal application, in the tools
subdirectory), it has a nice input level meter.  motv has one build-in
too (Menu -> Tools -> Record level monitor).

Note on stereo:  xanim seems not be able to playback stereo sound
correctly.


Video
=====

Note that video recording does not work if the Xvideo extension is in
use.  For recording stuff with xawtv you might have to start the
application with the -noxv switch to disable Xvideo.

xawtv/streamer handle video recording with multiple threads:

 - one thread records video (+ displays video on screen).
 - one (or more) thread(s) does color space conversion / compression.
 - one thread records audio (unless you do video only).
 - one thread writes the movie data to the disk.
 - one thread calls sync frequently to make the writeouts more
   smoothly (more smaller chunks instead of few very big ones).


There are buffer fifo's between the recording threads and the
compression / disk writer to avoid recording overruns due to a
temporarily busy hard disk or CPU load peaks.

If you see messages about a full fifo or about v4l(2) waiting for
free buffers it is very likely that your hard disk is too slow,
especially if you try to record uncompressed video.

bttv 0.7.x allows you to use more than just two video buffers, you can
configure the number at insmod time (gbuffers option).  Using more
buffers (say 4-8 instead of just two which is the default) should help
to reduce the number of dropped frames.

If you want to record quicktime movies install libquicktime
(http://libquicktime.sf.net), then (re-)build xawtv.  The configure
script should find the library automatically.


Known problems (and workarounds)
================================

The timestamping for the video frames isn't very exact as it does
_not_ come from the v4l(1) driver but is just a gettimeofday() call
after receiving the video frame.  API design bug, needs fixing.
With v4l2 xawtv uses the frame timestamps provided by the driver.


Troubleshooting syncronisation problems
=======================================

A/V sync should simply work if your box can keep up with the data
rate.  xawtv/streamer displays some debug info (time shift) on stderr.
"a/r" is the difference between audio and real time, "a/v" is the
difference between audio and video.

Ff you see "fifo full" error messages your box likely can't keep up
with the data rate.  Possible fixes: Try using more buffers.  Try
recording compressed video.  Try tuning the hard disk using hdparm.
Buy a faster hard disk.  Buy a faster computer.

If xawtv/streamer says "queueing frame twice" it has put a the same
video frame twice into the output queue to avoid video running out of
sync.  If this happens a lot it indicates that either your computer
can't keep up with compressing the frames or that your v4l device
can't capture frames with the frame rate you are asking for.  A single
message now and then is harmless.


MPEG Encoding
=============

Have a look at the mjpegtools (http://mjpeg.sourceforge.net).  xawtv
can write the yuv4mpeg format accepted by mpeg2enc directly.  mp2enc
accepts xawtv's wav files too.  So you can use xawtv/streamer,
mpeg2enc, mp3enc and mplex to build mpeg movies.

If you don't have enough disk space to store uncompressed yuv video
you can also record compressed quicktime/avi files and then recode
stuff using lav2yuv + mpeg2enc in a pipe.  The streamer help text
(streamer -h) has a few examples.


Large Files
===========

xawtv has LFS support, i.e. it can write files >2GB without problems.
The AVI format has a 2GB limit.  There is a extension to overcome this
[http://www.matrox.com/videoweb/news/press/papers/odmlff2.pdf], but not
all applications can deal with it.  The quicktime format usually works
better as there is the quicktime4linux library everybody uses to
read/write *.mov files, thus there are less compatibility issues.


Read, Convert, Edit + Playback stuff
====================================

Recent xawtv versions come with the "pia" utility.  That is a simple
player which should be able to playback all AVI and QuickTime movies
recorded by xawtv, motv and streamer.

avi format

 * xanim plays everything without problems.
 * QuickTime[tm] (MacOS) plays the uncompressed formats just
   fine and complains about mjpeg/jpeg.
 * Windows Media Player plays the uncompressed formats fine.
   mjpeg/jpeg work too if a codec is installed (/me has a very
   old one from MainConcept).
 * avifile can't deal with the uncompressed video correctly
   [fixed in recent versions].
   mjpeg/jpeg doesn't work either for me as it seems not to
   recognise the MainConcept codec, although I've copied
   stuff to /usr/lib/win32.  Maybe it works with another
   one.
 * MainActor (linux) can read the mjpeg but not the jpeg
   compressed files.


quicktime format

 * xmovie + broadcast2000 can read the files without problems
   (not exactly surprising as they use the quicktime4linux
   library too ...).
 * QuickTime[tm] (MacOS/Windows) plays them without problems.
 * xanim says it can't find any data in the mov file.  It used
   to work with older versions of the quicktime4linux library
   (before 64bit support was added), so I suspect xanim simply
   can't deal with 64bit mov files.


raw data

 * ImageMagick can deal with this, you have to specify the image
   format + size on the command line like this:
	display -size 320x240 rgb:file.raw
   It can handle multiple frames in one big file too.


Have fun,

  Gerd

--
Gerd Knorr <kraxel@bytesex.org>

translate motv app
==================

The new motif-gui version has i18n support, it is handled by using
different application default files for the different languages.  All
the strings are in the MoTV-<lang> files.  MoTV-default is the english
version.  MoTV-fixed has the other (language-independant) app-default
settings.  The Makefile merges these into MoTV.<lang>.ad files.

To add another language you just need to create a new MoTV-<lang>
file, edit x11/Subdir.mk and add the language to the LANGUAGES= line.
You can test the translations without "make install" this way (bash):

once at start:

$ cd x11
$ export XUSERFILESEARCHPATH="./%N.%l.ad:./%N.ad"
$ export LC_ALL=<lang>

every time after editing MoTV-<lang>:

$ make
$ ./motv


translate documentation
=======================

The applications come with a manual page as documentation.  Most manual
pages are in the man/ subdirectory.  Translated manual pages are very
welcome, I can easily add them to the distribution tarball.  It is a
good idea to add your email address to the translated page, so people
can reach you directly with spell fixes and stuff like that.  I can't
proof-read pages in foreign languages ...


other stuff
===========

Currently I have no plans to localize xawtv and the command line tools.

XFree86 4.x tips & tricks
=========================


DGA problems
------------

Release 4.0 has DGA turned off by default.  This is true for the first
release only, with current versions this shouldn't be a problem unless
you have some old config file still in use.

You'll have turn on DGA in XF86Config, otherwise v4l-conf will not
work correctly (Modules section, extmod options).  It should work for
most cards this way, althrouth some drivers don't handle DGA correctly
in 4.0 (that's why it is off...)

If DGA doesn't work for you, you have to configure bttv by hand (or
use Xvideo, see below).  v4l-conf has the "-a" switch for this.


using Xvideo
------------

XFree86 4.0 comes with a new X11 extention for video support.  The
X-Server will handle the grabber board then, not xawtv.  This has the
advantage that the X-Server knows about the video.  Window moves can
be handled without redraw problems.  The refresh triggered by xawtv
to fix it isn't required any more.  It is possible to use the video
scalers of modern graphics boards (see below).

To use Xvideo you have to load the video4linux module into the X-Server.
Just adding 'Load "v4l"' to the Modules section of XF86Config will do.
You have to make sure xawtv is compiled on a box with with XFree86 4.0
installed.  xawtv needs the new client libraries for Xvideo support.


using hardware scaling
----------------------

Starting with XFree86 4.0.1 the Xvideo extention supports hardware-scaled
video, i.e. the video isn't written directly to the visible area of the
video memory.  Instead the bt848 hardware writes yuv data to offscreen
memory.  The graphic card's video scaler does color space conversion and
video scaling.  This way fullscreen video works in 1024x768 (and greater)
without a black border because we are not limited to the maximum size
supported by the bt848 hardware any more.

As this is very new stuff not all drivers support video scaling yet.
It basically requires the overlay functions available to the
applications via xvideo port to be exported using a X-Server internal
interface too, so other X-Server modules are able to use them.

The mga driver was the first one which supported this (matrox
G200+G400).  XFree86 4.1 adds a few more ones, a quick grep of the
source tree returns this list: ct, i810, mga, nv, savage, smi,
trident.  For ati you might want to have a look at
http://www.linuxvideo.org/gatos/.

Detailed Status:
 * mga: works, I use that myself.  On multihead cards the second head
   is not accelerated, that means hw scaling via Xvideo works on the
   first head only.
 * i810: works, according to the drivers author which asked me some
   questions about it and finally got it going.
 * tdfx: current CVS version works, next release (4.1.1) will have it.
 * nvidia: free nv driver not working correctly (4.1).  nvidia's
   binary-only works starting with release 1512.
 * others: don't know, reports welcome.

You also need a bttv version newer than 0.7.16 (the 2.2.x kernel version
is /way/ to old, kernel 2.4.x is fine).  If both bttv driver and xfree86
gfx driver support it, xfree86's video4linux driver will use hardware
scaling automagically.


drawbacks
---------

capturing images/video doesn't work if xawtv runs using the Xvideo
extention.  With the '-noxv' switch Xvideo can be disabled.


multiheaded setups
------------------

"regular" multihead with two screens works just fine.  The one only thing
you have to take care off is that you can't use the -display option to
start xawtv on the second head if you are *not* using Xvideo.  Use
"DISPLAY=:0.1 xawtv" instead.  Otherwise v4l-conf will use the wrong
screen to configure the driver.

Xvideo + xinerama works just fine starting with XFree86 4.1, older
versions show video on the first physical screen only (the one listed
first in your ServerLayout section).  Without Xvideo you'll also see
the video on the first head only.

  Gerd