This is the README for kbtv-1.2.4 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. 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 TV card that's set up well, see btsetup - Or/and a Philips (pwc) based USB webcam that's set up well, see btsetup - SDL (for video rendering with bktr and saa) - 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 ============================== 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. Also the saa Python module is built, which has functionality for viewing, tuning, etc, exactly like the bt848 module for Brooktree 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. The latter is new as of kbtv-1.1.2, former versions had only PAL and NTSC as options. Secam doesn't work (yet). 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 ============================== 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. 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: rewrite & add pwc to 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 - Add user to operator group by login or UID kldload - Load bktr or saa or snd_driver (all snd_*) module sysctl 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: 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: mem 0xfea9fc00-0xfea9ffff irq22 at device 1.0 on pci6 iicbus0: on saa0 iic0: 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: port 0xb400-0xb41f irq 18 at device 2.0 on pci6 pcm0: 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 { 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 { 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!