This is the README for kbtv-1.1.3

About
=====

Kbtv is a small TV viewing application for KDE/FreeBSD, written mostly in Python.

Kbtv comes with an admin oriented utility btsetup that can be used to set permissions and ownership
right, setup your system to automatically load the bktr and/or the saa
and/or the pwc module, and the snd_driver module upon rebooting. It can 
also add users to the (required) operator group.

Kbtv is developed and tested on (approximately) FreeBSD 6-STABLE on i386 and
AMD64 (as of version 1.1.1). Version 1.1.2, should fix tuning problems with 
saa-based cards with an MK3 tuner. The latest 1.1.3 is a minor bugfix release.

Your feedback is welcome, please send it to danny@ricin.com and mention
kbtv in the subject line. Thanks!


To get it to run you need
=========================

- Python 2.3 or newer
- FreeBSD 5, 6 or 7
- A Brooktree (bktr) based TV card that's set up well, see btsetup
- Or/and a Philips (saa) based or compatible TV card that's set up well, see btsetup
- Or/and a Philips (pwc) based or compatible USB webcam that's set up well, see btsetup
- SDL (for video rendering with bktr and saa)
- PyGame (for video rendering with pwc), these are python bindings to SDL
- PyQt3 and PyKDE3 for the GUI
- Swig13 (to build bt848/saa/pwc wrapper modules)


To build/install there are the following make targets:
================

configure, build, install, deinstall, clean

The configure target is also run when the build target is run. Upon
install a package list file PLIST is written to this directory and upon
deinstall this is used to delete all installed files.

Normally you'd want to run

# make && make install clean

to install everything, and

# make deinstall

to deinstall all files. A file PLIST is written containing the full paths
of all files installed. If experimenting, don't forget to make clean.

For FreeBSD there is a regular port again which basically does the
build/install/deinstall things.


To install into a non-standard prefix or have other non-standard targets
=====================================

Change the installprefs.py file to your liking. You can change prefix, 
(s)bin, app, and doc dirs (relative to prefix). This file is read at 
install stage. If using the port, set PREFIX and leave installprefs.py
alone.


To build kbtv with SAA support
==============================

SAA support was added at RELEASE-1.0.

The saa driver, viewer, and support code from purpe.com is included with
kbtv. Build preferences can be set in buildprefs.py. If you set the
WITH_SAA variable to True the saa.ko kernel module will be built and
installed, as well as the SDL-based saaviewer. The tvv app that comes
with the saa tarball is not built anymore. It has been replaced with
the new viewer, which can be run stand-alone and gets embedded into kbtv.
Also a saa Python module is built that allows for tuning and such, exactly 
like the bt848 module provides for Brooktree based hardware.

An important difference between saa and bktr is that saa is always a kernel
module and it doesn't have sysctls for runtime setup. For tuning and many
other operations it uses the IIC (i2c) bus and interface (user space). Tuner
type and broadcast standard must be specified at build time using
buildprefs.py. 

Tuner types include Philips (default), Philips MK3 (found on boards that also 
support FM), Temic, Alps, and LG. Broadcast standards include PAL B/G, I, D/K,
L, L' and NTSC M/N, Japan (for SECAM try K, L, L'). The latter is new as of 
kbtv-1.1.2, former versions had only PAL and NTSC as options. Also, iic address 
doesn't have to be specified anymore, it can be probed at runtime. The saa 
Makevars are not used anymore, and the support code (for tuning) that comes 
with saa is not built anymore. Instead, IF init (if needed), tuner init, and 
frequency tuning is now done inside kbtv's saa module.

The devices created and used are /dev/saa0 (video), /dev/sau0 (audio),
/dev/iic0 (part of the core OS). Only the zero number devices are used at
this time to keep things simple.

If you have built kbtv with saa support _and_ the saa.ko module is loaded,
kbtv will default to using saa (providing bktr support also). If not, kbtv
defaults to using bktr only.


To build kbtv with PWC support
==============================

PWC support was added at 1.0.1 (never released).

The pwc driver from raaf.atspace.org is included with kbtv. In buildprefs.py
you can set whether or not you want it to be built and installed. It only
installs the kernel module, not the demo viewer. Pwc rendering is done
internally in the btbackend module.

The device created and used is /dev/video0 and it behaves like a V4L device.
If the camera was already plugged in when the kernel module is loaded, you
should pull it out and plug it back in (then restart devfs). This should not
be needed when rebooting while the camera remains plugged in.

The pwc driver is included in kbtv for convenience. The kbtv port uses the 
pwcbsd port to get the driver installed.


Requirements for hardware setup
===============================

BTSETUP and better backend integration were added at 1.0-RC3.

This is somewhat different than what a standard FreeBSD install would do.
It is REQUIRED that you are a member of the operator group and that the
operator group is the group owner of the bktr and tuner devices (not the 
symlinks, the real devices, e.g. bktr0). Standard FreeBSD/devfs makes 
wheel the group-owner. That's not good if you have untrusted users that
are allowed to access this hardware but not to become root. So that's why
operator is used. The btsetup utility can help you with the setup of
the ownership/group membership stuff and can also show you what currently
is your detected card and tuner unit and you can set and commit changes to
them (sysctl overrides). Of course you can also set this up manually. You
may need to do manual setup if you don't use bktr as a module or have no
devfs.

For saa, and the saa0, sau0, iic0 devices, things are similar. Since it has
no sysctl interface, btsetup commands like 'show tuners' are informative
only.

For pwc, things are similar too. Except for loading and committing
(permissions etc), all other btsetup commands like 'show cameras' are
informative only.


How to use btsetup
==================

BTSETUP and better backend integration were added at 1.0-RC3.

[ TODO: add pwc to this example ]

If you have no bktr/saa and/or snd module loaded yet, use the kldload command 
first. If needed you can set sysctl overrides for card and tuner with the 
sysctl command. Then use the commit command to write out the device, ownership
and kld setup (it appends to your config files, so while running commit more 
than once does spam those files it can't hurt to do so). At any time you can 
use the adduser command to add ordinary users to the required operator group.
Obviously, adminstrative tasks require that you're root.

An example says it best; here's how to it from scratch (no modules, no
devices, no nothing) on my desktop which currently has both a Brooktree and a
Philips based TV card. Comments are between { }, everything else is copied
verbatim.

desktop# btsetup
btsetup> h
help                      - Show this help text
show [cards|tuners|users] - Show current config or list cards, tuners, users
adduser <username|uid>    - Add user to operator group by login or UID
kldload <bktr|saa|snd>    - Load bktr or saa or snd_driver (all snd_*) module
sysctl <card|tuner> value - Set the sysctl for bktr card or tuner to value
commit                    - Commit/write the config (devfs, sysctl, loader)
quit                      - Quit btsetup
btsetup> show
BKTR - BrookTree/Conexant BT8x8 based cards
===================================================================
BKTR MODULE LOADED........... No
BKTR DEVICE PERMISSIONS...... Not OK

SAA - Philips SAA713x based cards
===================================================================
SAA MODULE LOADED............ No
SAA DEVICE PERMISSIONS....... Not OK

SOUND - Sound card and tuner sound wiring
===================================================================
SND MODULE LOADED............ No

{ Nothing has been set up yet }

btsetup> show cards
BKTR cards
==========
 0 Unknown
 1 Pinnacle/Miro TV
 2 Hauppauge WinCast/TV
 3 STB TV/PCI
 4 Intel Smart Video III/VideoLogic Captivator PCI
 5 IMS TV Turbo
 6 AVer Media TV/FM
 7 MMAC Osprey
 8 I/O DATA GV-BCTV2/PCI
 9 FlyVideo
10 Zoltrix
11 KISS TV/FM PCI
12 Video Highway Xtreme
13 Askey/Dynalink Magic TView
14 Leadtek Winfast TV 2000
15 TerraTVplus
16 I/O DATA GV-BCTV3/PCI
17 AOpen VA1000
18 Pinnacle PCTV Rave
19 PixelView PlayTV Pak
20 TerraTec TValue
21 PixelView PlayTV Pro REV-4C

SAA cards
=========
 0 Unknown card/vendor
 1 ADS Tech Instant TV
 2 ASUS TV-FM 713x
 3 AverMedia AverTV series (also Medion)
 4 Beholder BeholdTV
 5 LifeView FlyTV Platinum Mini2 (Compal)
 6 Compro VideoMate TV
 7 Elitegroup ECS TVP3XP
 8 LSA EX-VISION
 9 GoTView 7135 PCI
10 KNC One TV-Station DVR
11 LifeView FlyVideo
12 Matrox CronosPlus
13 Medion 7134
14 Philips (also Empress, SKNet, KNC/Typhoon, AOpen VA1000)
15 Pinnacle PCTV
16 RTD Embedded Technologies VFG73x0
17 Terratec Cinergy
18 Upmost Purple TV

{ Notes: - The bktr card's number should be used if you do 'sysctl card N'
         - The saa cardlist is compiled from (some) known vendor IDs and
           may be wrong or incomplete; an "unknown" card may work fine    }

btsetup> show tuners
BKTR tuners
===========
 0 None
 1 Temic NTSC
 2 Temic PAL
 3 Temic SECAM
 4 Philips NTSC
 5 Philips PAL
 6 Philips SECAM
 7 Temic PAL I
 8 Philips PAL I
 9 Philips FR1236 NTSC FM
10 Philips FR1216 PAL FM
11 Philips FR1236 SECAM FM
12 ALPS TSCH5 NTSC FM
13 ALPS TSBH1 NTSC
14 Microtune MT2032
15 LG TPI8PSB12P PAL

SAA tuners
==========
 0 Philips
 1 Philips MK3
 2 Temic
 3 Alps
 4 LG

{ Notes: - The bktr tuner's number should be used if you do 'sysctl tuner M'
         - The saa tuner API type is set at build time }

btsetup> kldload bktr

{ Shows the following on console and in dmesg:

bktr_mem: memory holder loaded
bktr0: <BrookTree 848A> mem 0xdfeff000-0xdfefffff irq 19 at device 3.0 on pci6
bktr0: [GIANT-LOCKED]
bktr0: MT2032: Companycode=3c3c Part=3c Revision=3c
bktr0: MT2032 not found or unknown type
bktr0: Pinnacle/Miro TV, Temic PAL tuner 

{ If you need to set overriding sysctls, now's a good time }

btsetup> kldload saa

{ Shows the following on console and in dmesg:

saa0: <Phillips SAA7134 AV broadcast decoder> mem 0xfea9fc00-0xfea9ffff irq22 
at device 1.0 on pci6
iicbus0: <SAA713x I2C Controller> on saa0
iic0: <I2C generic I/O> on iicbus0

  Note there's no tuner information, tuning is solely a user-space iic affair }

btsetup> kldload snd

{ Loads the snd_driver module, meaning ALL snd_* modules. This is for user
  convenience. Simply skip this step, and load your specific module later if
  you don't want all of them. If snd_driver is not loaded with btsetup it
  won't be put into your loader.conf either on 'commit' }

{ For your sound card(s), console/dmesg shows something like:

pcm0: <Creative EMU10K1> port 0xb400-0xb41f irq 18 at device 2.0 on pci6
pcm0: <SigmaTel STAC9721/23 AC97 Codec>

  Note that btsetup and kbtv only look at pcm0, not pcm1 or such }

btsetup> show
BKTR - BrookTree/Conexant BT8x8 based cards
===================================================================
BKTR MODULE LOADED........... Yes
BKTR DEVICE PERMISSIONS...... Not OK

SAA - Philips SAA713x based cards
===================================================================
SAA MODULE LOADED............ Yes
SAA DEVICE PERMISSIONS....... Not OK

SOUND - Sound card and tuner sound wiring
===================================================================
SND MODULE LOADED............ Yes
AUDIO CHIP................... Creative EMU10K1
MIXER CHANNEL FOR TV......... Line

{ That looks more like it. Note that if you have both a bktr and a saa
  card, the mixerchannel detection will likely be problematic if one uses
  line and the other line1. Live with it for now :) }

btsetup> commit

{ Does the nescessary things to have the modules loaded when booting and
  have the required device permissions and ownership }

btsetup> show
BKTR - BrookTree/Conexant BT8x8 based cards
===================================================================
BKTR MODULE LOADED........... Yes
BKTR DEVICE PERMISSIONS...... OK
BKTR CAPTURE CHIP............ BrookTree 848A
BKTR TV CARD................. Pinnacle/Miro TV
BKTR TUNER TYPE.............. Temic PAL

SAA - Philips SAA713x based cards
===================================================================
SAA MODULE LOADED............ Yes
SAA DEVICE PERMISSIONS....... OK
SAA CAPTURE CHIP............. Philips SAA7134
SAA TV CARD.................. AverMedia AverTV series (also Medion)
SAA TUNER TYPE............... Philips MK3 [iic 0xc2-0xc3]

SOUND - Sound card and tuner sound wiring
===================================================================
SND MODULE LOADED............ Yes
AUDIO CHIP................... Creative EMU10K1
MIXER CHANNEL FOR TV......... Line

{ Appended to /boot/loader.conf is the following:

## Appended by bthardware.py (kbtv) Mon Apr 10 17:29:53 2006
## BEGIN BKTR
bktr_load="YES"
## END BKTR

## Appended by bthardware.py (kbtv) Mon Apr 10 17:29:53 2006
## BEGIN SND
snd_driver_load="YES"
## END SND

## Appended by bthardware.py (kbtv) Mon Apr 10 17:29:53 2006
## BEGIN SAA
iic_load="YES"
saa_load="YES"
## END SAA

 Appended to /etc/devfs.conf is the following:

## Appended by bthardware.py (kbtv) Mon Apr 10 17:29:53 2006
## BEGIN BKTR
own  bktr0  root:operator
own  tuner0 root:operator
perm bktr0  0660
perm tuner0 0660
## END BKTR

## Appended by bthardware.py (kbtv) Mon Apr 10 17:29:53 2006
## BEGIN SAA
own  iic0 root:operator
own  saa0 root:operator
own  sau0 root:operator
perm iic0 0660
perm saa0 0660
perm sau0 0660
## END SAA

  If you have set sysctls for bktr there will be bt848.card and bt848.tuner
  entries appended to /etc/sysctl.conf as well }

btsetup> show users
root

{ I'm not in the operator group yet }

btsetup> adduser danny
btsetup> show users
root
danny

{ You can do this at any time, not necessarily during first setup }

If you need to set bktr sysctls, the best time to do it is before commit. 
You can do it later in the session or when running btsetup again later, but
to have them written out you'll have to run commit again. Commit writes to:
/boot/loader.conf (if you use modules, recommended), /etc/devfs.conf, and
/etc/sysctl.conf (if sysctls have been set before you commit) and it will do 
so every time.

To set things up manually:

- kldload modules, add them to /boot/loader.conf
- set sysctls if needed, add them to /etc/sysctl.conf
- make your TV users members of the operator group (not wheel)
- make operator the group owner of /dev/bktr0 and /dev/tuner0 (/dev/saa0,
  /dev/sau0, /dev/iic0 for saa)
- make the device permissions 660

Btsetup assumes devfs when dealing with the latter two (appends to
/etc/devfs.conf). If you have no devfs you need to use MAKEDEV or mknod,
and chmod, chown on the actual device nodes manually.

Btsetup only looks at bktr0/saa0 and pcm0, that is the first driver instance
and the devices attached to them, not higher numbers (mplayer only uses the
zero bktr and tuner devices anyway as does the saa code).


If you have been using an early kbtv version (prior to RC3)...
================================================================

Channel handling and managing has changed and so has the object representing
the user's channel list. This means any old list is incompatible and you'll
have make a new one from a frequency table or a local channelset or both.
In kbtv you can now process those one by one and ditch unwanted frequencies
before they even get in your personal channel list. The new location is in
~/.kde/share/apps/kbtv, you can delete any old ~/.kbtv directory. It is still
written out as a pickled Python object but also to a text representation.
Note that editing this text file will have no effect.


There are docs
==============

If you are having problems please read the kbtv "Handbook" first. If you're
interested in how the code works, it's fully documented with docstrings:

pydoc -w /path/to/kbtv_appdir

generates HTML formatted docs in the current directory for all modules.
On the interactive Python prompt you can use 'help(module_name)'.

Online documentation (may be outdated) at http://freebsd.ricin.com/kbtv.


If something doesn't work
=========================

Please let me know (as detailed as needed). I may not react immediately
or maybe not at all, but I will be keeping an eye on problem reports and
fix where I can. Please keep in mind that I'm doing this for fun and
education, and that I don't know everything.

I'd also like to compile a list of SAA based cards that are known to work,
so if you have one, let me know!
