Fxtv (BSD X TV)
Version 1.03
Written by Randall Hopper
URL: http://www.freebsd.org/~rhh/fxtv
1. PREPARATION
1.1 HARDWARE
To use this application, you need a video capture/tuner card
that's based on the Brooktree 848 capture chip, such as one of the
Hauppauge Wincast/TV or Win/TV cards, the STV TV PCI card, or the
Intel Smart Video Recorder III. See the BSD Bt848 driver page for
details:
http://telepresence.dmem.strath.ac.uk/bt848
1.2 THE DEVICE DRIVER
Once you have the hardware, you need the FreeBSD Brooktree 848
(bktr) driver. This version of fxtv uses the bt848.970604 driver, a
slightly modified version of the bt848.970424 which has better support
for the FPS ioctl call for running-video captures and throttled
display rate.
Normally, recent driver versions can be found at:
http://telepresence.dmem.strath.ac.uk/bt848
1.3 BUILD-TIME DEPENDENCIES
- A BSD OS (FreeBSD, NetBSD, OpenBSD, or BSDI)
- bktr driver
- tiff-3.3
- Xaw3d-1.3
- xpm-3.4j
- gmake-3.75
- XFree (tested on v3.2 and higher)
- VoxWare snd driver (3.0-beta-950506)
1.4 RUN-TIME DEPENDENCIES
- netpbm-94.3.1 (for tifftopnm)
- sox-12.12 (Audio Stream Conversions)
- mpeg_encode-1.5b (MPEG Video Encoder)
- dist10.tar.gz (MPEG Audio Encoder)
- mpg123 (MPEG Audio Player)
- mplex-1.1 (Mixes MPEG Audio/Video Streams into a
single MPEG System Stream)
Though not used by fxtv directly, you may find these useful as well:
- mtv (MPEG Video & System Stream Player - Fast!)
- mpeg_play-2.3 (MPEG Video Player)
Most of these are existing FreeBSD packages. The exceptions are
dist10, mtv, and mpg123. See Appendix A for info on how to get,
build, and install dist10. mtv is a Linux utility that can be had
from:
http://www.mpegtv.com/player.html
and mpg123 source is available at:
http://www.sfs.nphil.uni-tuebingen.de/~hipp/mpg123.html
Building it is a snap.
1.5 BUILDING AND INSTALLING FXTV
Installing the port is more desirable because you can then just
pkg_delete it when you want to upgrade to the next version.
1. Install the port
> tar -zxovf fxtv--port.tgz
> cd fxtv
> su
# make install
OR
2. Installing from the source package
> tar -zxovf fxtv-.tgz
> cd fxtv-
> gmake
> su
# gmake install
NOTE FOR FXTV USERS NOT RUNNING XFREE: Specify "HAVE_XFREE86=NO"
on the make command line to compile-out support for XFree86-specific
features. For example, when installing from the port:
# make HAVE_XFREE86=NO install
1.6 CUSTOMIZING FXTV
Modifying Fxtv's default behavior can be accomplished in one of two
ways: 1) modifying the Fxtv X resources (see the sample Fxtv resource
file, or 2) specifying command-line options.
Note that the command-line options in most cases have the same names
as the X resources. Refer to the delivered global Fxtv resource file
for resource file examples, and run:
fxtv -help
to display all the supported command-line options:
-driverDefaults - Use appearance parms from driver on startup
-colorbars - Turn on colorbar display (for testing)
-hue [-90...90] - Initial Hue ; def=0
-brightness [-50..50] - Initial Brightness (%); def=0
-contrast [0..200] - Initial Contrast (%); def=100
-satU [0..200] - U Saturation (%); def=100
-satV [0..284] - V Saturation (%); def=100
-fps - Display Speed (frames per second)
-noaspectlock - Disable 4:3 aspect lock on video window
-deviceNumber - bktr/tuner device numbers; def=0
-inputFormat [pal|ntsc] - Tuner signal input format
-tunerMode [cable|antenna] - Tuner Mode
-defaultInput - Startup tuner signal input
[tuner|video|svideo|csvideo|dev3]
-defaultAudioInput - Startup TV card audio input
[tuner|external|internal|auto]
-defaultChannel - Startup Channel Number
-cableStationList - List of cable stations presets(see rsrc file)
-antennaStationList - List of antenna stations presets
-cableFreqSet - Freq set for cable (def = cableirc)
[nabcst|cableirc|cablehrc|weurope|
jpnbcst|jpncable|xussr|australia|france]
-antennaFreqSet - Freq set for antenna (def = nabcst)
-noAudio - Suppress playing audio through soundcard
-dspDevice - Override default DSP device (/dev/dsp)
-mixerDevice - Override default mixer device (/dev/mixer)
-mixerChannel - Audio mixer (line,line1/2/3,cd,mic,video)
-stationInWinTitle - Display station text in window title
-stationInWinIcon - Display station text in window icon
-stationAnnotFont - Font pattern for station annot (see rsrcfile)
-stationAnnotColor - Color for station annot
-stationAnnotDelay - How long to display (0 = never; -1 = always)
-stationAnnotIDOnly - Display station ID alone (when available)
-remoteType - Type of attached remote control
[None|X10|Hauppauge|PixelView]
-recCmdMpeg2 - MPEG-2 Audio record command
-recCmdMpeg3 - MPEG-3 Audio record command
-playCmdMpeg2 - MPEG-2 Audio play command
-playCmdMpeg3 - MPEG-3 Audio play command
-videoCnvtScript - Video convers workhorse script for vid encod.
-bswap2Bpp - Byte/word swap options for direct video
-nobswap2Bpp (used to match driver's pixel format with
-bswap3Bpp the video card's)
-nobswap3Bpp
-bswap4Bpp 2Bpp - 15/16-bpp modes
-nobswap4Bpp 3Bpp - packed 24bpp modes
-bwwap4Bpp 4Bpp - unpacked 24bpp modes
-nowswap4Bpp
-Bpp24bit [3|4] - Set frame buff Bytes-per-pixel for 24bpp mode
-Bpp32bit [3|4] - Set frame buff Bytes-per-pixel for 32bpp mode
-videoCapFile[1-4] - Optional paths (0-4) to scratch file paths
to use for vid capt; spread load across disks
-noafc - Disable AFC
-disableDirectV - Disable DMA transfers straight to video card
-debug - Debug Msgs
{startup,subproc,events,subproc,video,frame}
-help - Display program options
1.6.1 CUSTOMIZING STATION PRESETS
---INTRODUCTION:---
Fxtv supports two tuner modes: "cable" and "antenna". Each of these
two modes can be assigned a frequency set, which determines the
frequency-to-channel-number mapping for the tuner mode (which are set
via the antennaFreqSet and cableFreqSet resources). The frequency set
you choose for each tuner mode will depend on where you live and who
your NTSC or PAL signal providers are. For example, in the US (NTSC),
you probably want to use:
Fxtv.antennaFreqSet: nabcst
Fxtv.cableFreqSet: cableirc
As with any standard NTSC or PAL TV or VCR, Fxtv supports "station
preset lists" for each tuner mode (cable and antenna), which
effectively define the hot-list of stations you will be surfing.
Station preset lists are specified via the:
Fxtv.antennaStationList:
Fxtv.cableStationList:
resources.
Here's how Fxtv models preset lists: Each in a
is associated with a specific or a specific .
Optionally, each may be also associated with a ,
which is a convenience name used to refer to the station preset
(e.g. "E10","ITD",... for the PAL folks; or "FOX","CBS",... for the US
folks).
When specified, s can be used for keying-in station changes
and will also be displayed on the Fxtv window to reflect the current
station. Whether s are specified or not, s
and s can be used to key-in station changes, and will be
used for display in the absense of a .
If you associate a preset with a , when the preset is made
active, that channel number is passed to the Bt848 driver which in-turn
maps it to a frequency (using the frequency set you configured for that
tuner mode). This frequency is used to configure the tuner.
If, on the other hand, you associate a preset with a , the
frequency itself is passed to the Bt848 driver, bypassing its
channel-to-freq conversion. Again, this frequency is used to configure
the tuner.
Specifying a station in terms of its frequency can be useful when the
driver doesn't have an accurate channel-to-freq mapping for all
of the stations used in your area.
---SYNTAX:---
With that preamble, here's the Fxtv syntax for encoding a :
:= [|] ...
:=
F()
(F)
:= - := a positive integer
:= a floating point number, in MHz
Note that s are treated as case insensitive.
---EXAMPLES:---
And here are some StationList examples:
1) Fxtv.antennaStationList: ITA(f471.25) ITC(15) E32(21) 22-24 99
2) Fxtv.antennaStationList: 3 ABC(5) PBS(f169.00) 83(f61.25)
3) Fxtv.cableStationList: 3-5 19-21 23
In the first example, the station-id "ITA" is associated with the
frequency 471.25 Mhz (with this, either "ITA" or "f471.25" may be used
to key-in a station change to this station). The station ID "ITC" is
associated with channel "15" in the frequency set configured for the
"antenna" tuner mode. "E32" is associated with channel "21". And
the channels 22, 23, 24, and 99 are also defined without explicit
station IDs (and thus the station-ids are defaulted to be the channel
numbers themselves). The first example is equivalent to the following
resource definition:
Fxtv.antennaStationList: ITA(f471.25) ITC(15) E32(21) 22(22) \
23(23) 24(24) 99(99)
The second example is like the first. Notice station-id 83 though.
With station IDs you can override the default channel-num-to-frequency
mappings (or put some into place where they didn't exist before -- the
more likely case). And yes, you can also drive yourself nuts by
remapping channel numbers to other channel numbers if you want
(e.g. "3(5) 5(3)" seemingly swaps channels 3 and 5).
Note that these examples are a bit contrived just to demonstrate the
syntax. For instance, you probably won't associate station presets
directly with frequencies unless the driver doesn't have channel
presets for all the stations you receive. When the driver does have
the needed channel presets, with AFC on and presets associated with
channel numbers, the tuner will usually be able to zero-in on the
station if its slightly off of the channel frequency (the same as if
you define a preset with a frequency that's slightly off).
1.6.2 CHANGING STATIONS
Fxtv provides several ways for the user to change stations:
1) Station Up/Down Arrow Buttons (on taskbar)
2) Station Text Widget Key-in (on taskbar)
3) Video Window Key-ins
4) Video Window Action Routines
The Station Up & Down buttons are straightforward. These move through
your predefined station list for the currently selected tuner mode in
the direction indicated by the button icon.
The Station Text Key-in allows you to change to any predefined station
or arbitrary channel number or frequency. Acceptable values are:
1) the station IDs you've defined in your station list,
2) channel numbers, and
3) frequencies (prefix with "F" when entering).
Examples: "E1", "FOX", "23", "f61.25".
Video Window Key-in allows you to type in channel numbers directly on
top of the video window. The format is the same as with the text
key-in, except that station ID entry should be prefixed by "C". This
is for compatibility with action routines. Examples: "cE1", "cFOX",
"23", "f61.25".
And finally, Video Window Action Routines provide the user a way to
redefine the keys on their keyboard to change stations the way the user
prefers when the X pointer is over the video window. Station changes
may be specified both relative to the current station, or absolutely
(by specifying a station ID, channel number, or frequency). An example
first, followed by explanation:
Fxtv*videoWin.translations: #override \
+ : TVSetStation( +1 ) \n\
- : TVSetStation( -1 ) \n\
KP_Add : TVSetStation( +1 ) \n\
KP_Subtract : TVSetStation( -1 ) \n\
F6 : TVSetStation( FOX ) \n\
F7 : TVSetStation( 23 ) \n\
F8 : TVSetStation( f61.25 ) \n\
F9 : TVSetStation( -f ) \n\
F10 : TVSetStation( +f ) \n
The first 4 bind both pairs of "+" and "-" keys to perform relative
station changes. The 5th defines F6 to set the station to the one with
the station ID "FOX". The 6th defines F7 to change to the station to
channel 23 (assuming no station with an ID of "23" exists, in which
case it would take precedence). The 7th defines F8 to change station
to a frequency of 61.25 MHz. And the last two bind F9 and F10 to
increment and decrement frequency in small increments.
Note that "no-op()" has been registered as a valid action routine
for convenient unbinding of translations.
Having read 1.6.1 and customized your station presets (key in: "ITC" or
"15").
1.6.3 CONFIGURING A REMOTE CONTROL
At this time, the X10 MouseRemote, Hauppauge, and PixelView remote
controls are supported.
1.6.3.1 X10-SPECIFIC CONFIGURATION
Both stand-alone and system-mouse pass-through configuration are
supported in X. Both require an updated version of moused (see
moused(8)), which has support for the X10 MouseRemote.
My moused patch for X10 remote support is included with this verions of
Fxtv, though it may already be incorporated into your moused. You can
determine whether it has by running moused as follows:
moused -p /dev/cuaa0 -t x10mouseremote -3
substituting the path to the serial port your mouse is attached to
in place of /dev/cuaa0. If you see:
moused: no such mouse type `x10mouseremote'
It hasn't and you need to rebuild moused with the patch. Get it here:
http://www.freebsd.org/~rhh/fxtv/moused.x10remote.patch
And apply it like this:
# cd /usr/src/usr.sbin/moused
# patch < moused.x10remote.patch
# make
Now you're ready to go. Kick off moused on the MouseRemote serial
port (if you haven't already). For example, if your MouseRemote is
plugged into COM1 (cuaa0):
moused -p /dev/cuaa0 -t x10mouseremote -3
You may just want to configure this into your rc.conf so it's run each
time you boot up.
Next, insert these lines in your Fxtv resource file:
Fxtv.remoteType: X10
You're ready to use your remote control! Run Fxtv and play around with
it to make sure things are working. If you have trouble,
run "fxtv -debug remote" to see whether fxtv is getting any remote
events.
1.6.3.2 HAUPPAUGE-SPECIFIC CONFIGURATION
Simply insert these lines in your Fxtv resource file:
Fxtv.remoteType: Hauppauge
and you're ready to use your remote control! Run Fxtv and play around
with it to make sure things are working. If you have trouble, run
"fxtv -debug remote" to see whether fxtv is getting any remote events.
1.6.3.3 PIXELVIEW-SPECIFIC CONFIGURATION
Simply insert these lines in your Fxtv resource file:
Fxtv.remoteType: PixelView
and you're ready to use your remote control! Run Fxtv and play around
with it to make sure things are working. If you have trouble, run
"fxtv -debug remote" to see whether fxtv is getting any remote events.
1.6.3.4 COMMON CONFIGURATION
Now that you've played with it, you probably will want to custom
configure some of the buttons to behave differently than the default
configuration. To do so, set up the remoteTranslations resource in
your Fxtv resource file. You can map any button to any provided
Fxtv action routine, similar to the way you can for mouse events
and keyboard keys. For example:
! User-defined Remote Control Translations
Fxtv.remoteTranslations: \
ChanUp : TVSetStation( +1 ) \n\
ChanDn : TVSetStation( -1 ) \n\
VolUp : TVSetVolume( +1 ) \n\
VolDn : TVSetVolume( -1 ) \n\
Mute : TVToggleMute() \n\
Disp : TVToggleZoom( fullscreen ) \n\
A-B : TVSetCaptureInput( +1 ) \n\
Pause : TVToggleFreeze() \n\
Rec : TVVideoRecordStart() \n\
Stop : TVVideoRecordStop() \n\
Power : TVQuit() \n
Here is the list of key names supported by the X10 Remote
(case insensitive):
Power,AllOn,PC,CD,Web,DVD,Phone,0,1,Home,2,Up,3,PgUp,4,Left,5,6,
Right,7,End,8,Down,9,PgDn,ENTER,VolUp,BrightUp,VolDn,BrightDn,
ChanUp,On,ChanDn,Off,MUTE,AllOff,A-B,DISP,PLAY,REW,FF,STOP,REC,
PAUSE,LAST
Here is the list of key names supported by the Hauppauge
Remote (case insensitive):
0,1,2,3,4,5,6,7,8,9,Radio,Mute,Tv,VolUp,VolDn,Reserved,
ChanUp,ChanDn,Source,Minimize,FullScreen
2.0 SAVING IMAGES -- TIPS
Fxtv now supports saving of the last frozen image to disk.
Saving in TIFF and PPM formats is supported.
Fxtv can save the pic in the filename you specify, or that filename
with an image number appended. The latter is useful when you want to
capture a lot of stills on-demand (freeze, snap, freeze, snap, ...).
The action routine TVSaveImage() is provided for binding image save to
keyboard key or mouse button for repetitive on-demand image captures.
3.0 SAVING AUDIO -- TIPS
Saving audio streams to disk (and playing the resulting streams) is now
supported in the following formats:
RAW WAV
AU AIFF
VOC MPEG (Levels 2 & 3)
The capture sample format, frequency, and number of channels can be
specified as well.
RAW and AU are supported without the aid of external programs. The
rest require that "sox" be installed (and in the PATH).
In addition, MPEG Level 2 & 3 support also require that MPEG audio
encoder and player utilities be installed. The recommended player is
"mpg123", and the recommended encoder is the one from dist10 (see
RUN-TIME DEPENDENCIES above).
The MPEG player and encoder utilities are identified to Fxtv via X
resources in the Fxtv resource file:
! Custom MPEG record and play commands
Fxtv.recCmdMpeg2: mpeg_musicin -l 2 -p 1
Fxtv.recCmdMpeg3: mpeg_musicin -l 3 -p 2
Fxtv.playCmdMpeg2: mpg123
Fxtv.playCmdMpeg3: mpg123
TIP: If audio save and/or play doesn't seem to be working, fxtv
probably can't find "sox" or the mpeg encoder/player programs.
Try:
fxtv -debug subproc
for more verbose output.
3.0 SAVING VIDEO -- TIPS
Three useful video targets are supported:
Images
MPEG Ready
MPEG
With each, audio may optionally be saved at the same time.
The image format, capture resolution, capture rate, audio format, and
audio rate can also be specified. A simple frame rate optimizer is
provided as well.
Selecting the "Images" target causes Fxtv to convert the captured
video stream into a sequence of numbered images in the specified format.
If audio save is enabled, audio will be simultaneously captured, and
post-converted to the specified format.
Selecting the "MPEG Ready" target causes Fxtv to capture images and
audio as with "Images", with a few additions. The frame rate
is buffered to 30 frames per second, and an mpeg_encode parameter file
and convenience "go" shell script are created so the user is ready
to tweak the encoding parameters and kick it off on their own.
Finally, selecting "MPEG" is like "MPEG Ready" except that Fxtv manages
the entire process of running the conversion and encoding programs,
informing the user of the current encoding status via dialogs.
This is useful for grabbing video and building an MPEG as quickly and
simply as possible.
TIP #1 -- IF VIDEO SAVE/ENCODE DOESN'T WORK
As with audio save, if video save doesn't seem to be working,
try:
fxtv -debug subproc
TIP #2 -- MPEG_ENCODE FRAME RATE LIMITATIONS
mpeg_encode, used to convert a sequence of images into an MPEG-1
video stream, is limited to frame rates of:
{23.976, 24, 25, 29.97, 30, 50, 59.94, 60}
So in general you'll get better results if you choose frame rates of
24, 25, or 30.
TIP #3 -- OPTIMIZING FRAME RATE
First, use the "Fxtv.videoCapFile[1-4]" resources to specify up to
four different files to interleave raw video/audio capture to. If
you point these resources to paths on different disks, you'll get
much higher bandwidth than you would with just one disk (the default).
The "Optimize" control provided here is a first-cut and too
simplistic. It blasts 100 frames at 30 fps to the disk at the
target resolution, and (averaging across blocking disk writes) it
looks at how long this process took to estimate the approximate
frame rate your disk might sustain without long hickups.
For now, you can probably eyeball a better estimate by running fxtv
like this:
fxtv -debug video
and doing RAW format captures at your target resolution and frame
rate. Watch the output fly by in your xterm. If you see half- to
whole-second delay "hickups", back the frame rate off a bit and
repeat until you see a fairly constant "gate" in skipped frames.
TIP #4 -- DRIVER BUG
Temporal decimation doesn't work perfectly in the driver yet. As
before, 30 fps will work fine at any resolution. With the 970604
driver, FPS adjustment < 30 should work OK for single-field captures
(i.e. num pixel rows <= 240). However, double-field captures
(i.e. num pixel rows > 240) at < 30fps don't work yet, so avoid that
combination. With a driver rev dated pre-970604, don't even bother
with anything other than 30fps.
APPENDIX A - BUILDING MPEG LAYER 2 & 3 ENCODER SOFTWARE
First, grab dist10.tar.gz from:
http://www.pagesz.net/~aa8vb/fxtv, or
ftp://ftp.tnt.uni-hannover.de/pub/MPEG/audio/mpeg2/software/technical_report
Then:
tar -zxovf dist10.tar.gz
cd dist10/lsf/encoder
./configure
gmake
mv encode /usr/local/bin/mpeg_musicin
find tables -print | cpio -dumpv /usr/local/lib/mpegaudio
cd ../decoder
./configure
gmake
mv decode /usr/local/bin/mpeg_musicout
and finally, put this env var setting in your profile:
MPEGTABLES=/usr/local/lib/mpegaudio/tables
NOTE: For every last pinch of speed, after each "configure", modify
the Makefiles and change "-O" to "-O3 -ffast-math -mfancy-math-387".
NOTE: An older version of this software is packaged as the FreeBSD
"mpeg_audio" port, but it doesn't like some AIFF files (byte order
problems), and it doesn't seem to do Level 3 audio. dist10 does.
APPENDIX B - MINIMIZING SCREEN CORRUPTION WHEN USING DIRECT VIDEO
Disable SaveUnders and BackingStore in your Window Manager configuration
to minimize the occurance of stray video trash that may appear on your
desktop when moving and resizing the Fxtv window while Fxtv is
in direct video mode.
Note that you can also use the "Refresh Screen" window manager function
to clean up any spurious trash as well.
FWIW, the author uses the AfterStep window manager and hardly ever sees
stray video trash left on the desktop or another client window.
APPENDEX C - LICENSING AND DISTRIBUTION DETAILS
The license and distribution terms for any publically available version or
derivative of this code cannot be changed. i.e. this code cannot simply be
copied and put under another distribution license
[including the GNU Public License.]
______________________________________________________________________________
______________________________________________________________________________
Have fun!
All suggestions, bug reports, fixes, and enhancements welcome. Please
mail to multimedia@freebsd.org.