Kbtv"> ]> Danny Pansters

danny@ricin.com

2005-2007 Danny Pansters 2007-05-09 1.2.5 &appname; is a TV viewer for FreeBSD. KDE &appname; bktr saa TV &appname; is a small TV viewing application for KDE/FreeBSD, mostly written in Python. It supports BrookTree (Conexant) based TV cards (bktr driver) and as of 1.0 (April 2006) also Philips SAA713x based TV cards (saa driver from purpe.com). As of version 1.0.1 (May 2006) it also supports the Philips/Logitech based webcams that work with the pwcbsd driver from raaf.atspace.org. &appname; 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 TV operator group. If you have a supported capture card without a tuner, you can still use &appname; to display composite video, for example from a satellite receiver, and connect the audio source to your capture card's line-in (if it has one) or one of your soundcard's line inlets. For video displaying, &appname; uses SDL. Release 1.2 features saa tuning improvements, integrated rendering (no more stand-alone apps for bktr and saa rendering), and smoother changing of rendering size and driver. Releases 1.2.1 to 1.2.5 are mainly bugfix releases. &appname; consists of several non-GUI modules (starting with bt*) that can be used as-is as a framework for another app or for lower-level operations. The GUI modules (starting with kbtv_*) use the PyKDE (and PyQt) bindings. The saa code is included with &appname; for convenience (&appname; has build time configuration switches for tuner type and broadcast standard, but it does not use the saa support code for tuning anymore as of version 1.1.2). Please see the README file more more details about saa. Likewise, currently the pwcbsd driver code is also included with &appname; (there's also a FreeBSD port for it), as there is a build-time requirement for its code. Please see the README file more more details about pwc. &appname; comes with a utilty called btsetup to assist you with loading and setting up the bktr/saa and snd_driver modules if not already, and to set sysctl overrides for your card or tuner if you need them. It's meant to be run as root if you intend to commit changes to your setup, it can be run as your regular user account if you only want to retrieve setup info or list the supported cards or tuners. The README file distributed with &appname; contains a full example of how btsetup is used to set things up from scratch. Btsetup can also be used to add users that may use the TV card hardware. These _must_ be made members of the operator group and the bktr and tuner devices _must_ be owned root:operator and be group-writable. Btsetup does it for you. Btsetup assumes devfs and will try to append to /etc/devfs.conf and restart devfs. Entering "help" or any non-expected command on the btsetup prompt will show its built-in help text. Btsetup uses the bthardware.py module and will always only append to your config files and never remove any settings that were present already (it doesn't even read or parse them). &appname; will show a warning message box if the setup is not to its liking. Don't expect it to run properly if you get such a warning. Finally, it's recommended to use kernel modules for bktr and snd_* support rather than building them into your kernel. That's really not needed in most cases. Btsetup uses kld modules if you let it have its way. &appname; has not been tested with bktr/snd built into the kernel. The saa driver can only be built and used as a module, likewise for the pwc driver FreeBSD 5, 6 or 7 Python 2.3 or newer SWIG (1.3 or newer) to build bktr/saa wrapper modules 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 or compatible USB webcam that's set up well, see btsetup SDL for video rendering PyQt3 and PyKDE3 for the GUI If anything's missing this should be discovered during the configure or build stage (and it should halt right there). The installprefs.py file can be edited to change installation prefix and such. If you want to build &appname; with support for SAA based cards you should edit the buildprefs.py and set the variable USE_SAA to True. You should also set the appropriate tuner type and video standard in buildprefs.py before building &appname; with saa support. If you want pwc support and driver, add USE_PWC to buildprefs.py. To build and then install from the source directory: # make # make install [clean] To deinstall &appname; from your system, again from your source directory: # make deinstall [clean] Or you can run the deinstall script from the &appname; installation directory: # python do_deinstall.py If using the port, just choose the appropriate OPTIONS. Make sure to select only one tuner and only one standard. Use 'make config' to revise your compile-time preferences. Main window of &appname; &appname; main window screenshot &appname; has a document-view-like GUI with menu entries for moving up and down the channel, and for showing dialogs for channel management, hardware info, and picture settings (brightness, etc). It also allows you to switch to full-screen mode, switch driver and rendering backend between bktr and saa (if saa is available) and pwc (if pwc is available), change display size, to change the mixer channel that's controlled by &appname; and to move the volume level up and down. All these actions have accelerator and shortcut keys for quick control by keyboard. The toolbar contains the most common actions: channel up/down, entering a channel number manually in an input box, changing the volume with a slider, and switching to and from full-screen mode. The statusbar shows which station you're tuned to and its number and frequency or device ID, or if &appname; is in editing mode. &appname; has functionality for managing your channels: you can edit them, move them around in the list, add channels from a list of frequencies, from a channelset, or add a composite "channel" or a combination of these. The section on dialogs below shows how this works. By default AFC (Automatic Frequency Control) is turned on, as it enables the tuner to automatically float between -2 and +2 MHz around the target frequency and pick the best one (bktr only, not saa). This can be of great help if you don't have (your provider's) frequency set. For every frequency to be added you can still manually set the frequency -2 to +2 around the targetted and normally AFC'd frequency for every channel and you can accept or reject them one by one. After that you can still reject the whole list and even after adding to the channel list you can reset to the old list if you don't like your changes. &appname; Channels menu &appname;'s Channels menu The Channel menu contains actions to tune up and down your channel list (cyclic), corresponding with the up and down buttons in the toolbar. Shortcut keys are the PgUp and PgDown keys, for your fast zapping enjoyment. The channel input box in the toolbar can also be used if you like to enter the channel number manually (hit enter afterwards). This menu also contains the Quit action, with the usual shortcut key combination of Ctrl+Q. &appname; Tools menu &appname;'s Tools menu The Tools menu is for special dialogs you sometimes need but not often. You can launch the Channel editor dialog from it to manage your channel list, and the Hardware info dialog which is only informational. Shortcut keys are F10 and F11. If using the pwc driver, there's no Channel editor entry (it's greyed out). &appname; Settings menu &appname;'s Settings menu The Settings menu is for things you may want to adjust more often. It contains a toggle to and from full-screen mode (or just hit F9). In full-screen mode only the toolbar is shown (it's sufficiently small to not make the slight aspect distortion noticable). The full-screen toggle is also the first item of the toolbar. Next you can invoke the Picture settings dialog from this menu. It allows you to set brightness, contrast, color balance, and color saturation. The shortcut key is F12. &appname; Driver Settings &appname;'s Driver Settings The Driver menu item provides a means to switch between bktr, pwc, and saa drivers, and their respective viewers. This is only available if &appname; has saa and/or pwc support. Shortcut key combinations are Alt+b, Alt+s and Alt+p respectively. &appname; in Webcam modus &appname;'s Webcam GUI If you switch to pwc from bktr or saa, the Channel menu entries for Up and Down change into Up/Down and Left/Right and their actions are to pan and tilt the camera (if your hardware supports it). They also appear in the toolbar. The channel input box in the toolbar is not functional in webcam mode, the volume slider is, and it will default to the "Mic" mixer channel (microphone). In the screenshot above, a Logitech cam is used (one of those "balls" that can tilt and pan). &appname; Size Settings &appname;'s Size Settings To change the viewer size you can use the size submenu under Settings. Shortcut keys are F6, F7, F8 respectively for small size (200x150), medium size (400x300) and large size (the actual frame size when using a TV card, 640x480 or 768x576; SDTV 720x576 gets scaled up to 4:3 aspect). For pwc, the capture size is currently fixed at 320x240. This may not work out too great for some cameras. The main window screenshot above is a snapshot taken with a Logitech cam (one of those "balls" that can tilt and pan). &appname; Mixer Settings &appname;'s Mixer Settings The mixer settings submenu allows you to set the mixer channel to be used when controlling the volume. You need to have your TV card's audio-out wired to your soundcard's audio-in (line/aux). By default 'Line' will be selected and used at first, but if it should be another (e.g. line1 if connecting TV card audio-out with sound card line-in from card to card rather than connecting them on the outside of your computer) or if you want another temporarily (for example if using a satellite receiver through composite with its sound plugged into one of your soundcard's inlets), you can change it here. The list will show (if present): line, line1 to line3, mic, and video. This submenu is a new feature as of version 1.2.2. Shortcut keys are ALT+1, ALT+2, etc (as many as you have). &appname; Volume Settings &appname;'s Volume Settings Finally, you can turn the volume up or down by five percent points using the Volume menu item. You'll probably rather use the slider in the toolbar, or the shortcut keys, - and +. &appname; help menu &appname;'s Help menu You are probably already familiar with the Help menu, since you likely used it to launch the KDE Help Center with this handbook. There's not much to say about it, other than that the What's this functionalty is not implemented. Last but not least, as of version 1.2 you can use Space to (un-)pause the video. Channel editor &appname; channel editor dialog The Channel editor can be invoked from the Tools menu or by pressing the shortcut key F10. This is a modal dialog, you can't interact with &appname;'s main window while it is opened. In the list of channels you can click on the one you want to edit. With the up and down buttons on the left you can move its position and with the delete button on the right you can delete it. The name for the selected channel can be changed in the input box in the middle (changed after you hit enter). The green Add channels button invokes the dialog to add new channels which is explained next. With the Reset button you can reset the channel list to what it was when you invoked this dialog, and OK and Cancel accept or reject the changes you made. If you have no channels set up yet, &appname; creates one entry at channel number 0 for your first, and in many cases only, composite device. This can be used with a satellite receiver or a video camera, or any device that has an analog composite outlet. Add channels &appname; add channels dialog To add new channels you can add a list of frequencies (separated by whitespace). This is mostly useful if you already have a list of frequencies from your (cable) provider, or if you want to add one or a few missing ones or maybe to experiment. You can also choose a local channel set and use the frequencies from that. Sometimes another channel set than your locale may have more or all frequencies you need. Experiment if needed. It's generally recommended to use AFC, but if you must you can turn it off. AFC will pick the optimum frequency in the range between -2 and +2 MHz around the requested frequency. It is somewhat slower though, because the hardware needs to tune twice. The saa driver doesn't have AFC (but your tuner might do it internally). Finally you can pick a composite device to be added as a channel. If any composite or frequency (after AFC and/or adjusting manually) is already in the channel list it will be ignored when adding. If you press OK and you entered one or more frequencies or chose a local channel set, you'll get the Processing dialog which is explained next. You can still reject any channel candidate there. Process candidate channels &appname; channel processing dialog The screenshot above shows the Processing dialog after the first of the three requested frequencies has been accepted. Note that the second (201 MHz) is automatically changed to the optimum of 200 MHz. This is AFC at work. For every channel candidate you can accept or reject it and you can also manually fine tune the frequency between -2 and +2 around the target, should this be needed. If all candidates have been shown and decided on the OK and Cancel buttons become enabled and you can decide if you want these channels to be added to your list. Duplicates will be silently ignored. Hardware info &appname; hardware info dialog The Hardware info dialog can be invoked from the Tools menu or by pressing the shortcut key F11. It is an informational dialog showing the same things as the "show" command on the btsetup prompt would. It's a non-modal dialog, you can use &appname;'s GUI while it is opened. If you switch drivers, the hardware info is updated to reflect the details of the selected card/driver. Picture settings &appname; picture settings dialog The Picture settings dialog can be invoked from the Tools menu or by pressing the shortcut key F12. It allows you to change the brightness and contrast, and the color balance and color saturation. It's a non-modal dialog, you can use &appname;'s GUI while it is opened. PageUp Channel Up Tune to next channel PageDown Channel Down Tune to previous channel &Ctrl;Q Channel Quit Quits &appname; F10 Tools Channel editor... Invokes the channel editor dialog F11 Tools Hardware info... Invokes the informational hardware info dialog F9 Settings Full screen mode Enter or leave full screen mode F12 Settings Picture... Invokes the picture settings dialog F6, F7 and F8 Settings Size Lets you switch between display sizes small, medium and large Alt+B, Alt+S and Alt+P Settings Driver Lets you switch between bktr, pwc and saa driver Alt+1, Alt+2, ... Settings Mixer Lets you change mixer channel to control its volume + and - Settings Volume Lets you increase or decrease the volume in steps of five percent points Space can be used to (un-)pause the video &help.menu.documentation; DCOP interface &appname; DCOP functions (kdcop screenshot) DCOP is the KDE protocol for inter-process communication between two KDE apps. It means that you can script a KDE app through DCOP or access a running instance from another application directly. &appname; exports all GUI actions and some other get/set methods, providing a complete DCOP interface. You can display and play with them using the kdcop app or the dcop command line utility that both come with KDE. Please note that the above screenshot may be outdated. Always look at (k)dcop's output or the kbtv_dcop.py module if you want to be current. All Python modules are liberally documented with docstrings. To extract them to HTML files use pydoc -w module_name. There's also quite a lot of comments in the code. The non-GUI modules can be used seperately as building blocks for another app. All of &appname; is BSD licensed. Happy hacking! Program copyright 2005-2007 danny@ricin.com &underBSDLicense; &documentation.index;