.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TVSIM 1"
.TH TVSIM 1 " " "tvsim 2.1 (C) 2002,2005 Tom Zoerner" "TV app interaction simulator"
.SH "NAME"
tvsim \- TV application interaction simulator
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBtvsim\fR [\ options\ ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBtvsim\fR
is a demo application that shows in which ways nxtvepg can cooperate
with \s-1TV\s0 applications.
It's also a reference implementation of the communication protocols
and offers most of the source code (under the \s-1GPL\s0 license) that would
be required to add \s-1EPG\s0 support to a \s-1TV\s0 application.  If you want to
add nxtvepg to a \s-1TV\s0 application, it's recommended to start with the
code of tvsim's source modules, remove everthing you don't need (esp.
the Tcl/Tk \s-1GUI\s0 and support for all but one protocols), put it in a
library and link it to your \s-1TV\s0 app.
.PP
In the current version two protocols are supported: On \s-1UNIX\s0 an X11 atoms
based protocol which allows interaction with \fIxawtv\fR and \fIxawdecode\fR.
On Windows a shared memory based protocol which allows interaction
with \fIK!TV\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
Summary of command line options (it's a sub-set of the options
supported by nxtvepg):
.IP "\fB\-geometry\fR \fIgeometry\fR" 4
.IX Item "-geometry geometry"
Specifies the position of the main window, e.g.  \fB\-geometry \-0+0\fR
to put the main window in the upper right corner of the visible screen.
The size of the window cannot be changed.
.IP "\fB\-iconic\fR" 4
.IX Item "-iconic"
Start with the main window iconified (i.e. minimized).
.IP "\fB\-rcfile\fR \fIpath\fR" 4
.IX Item "-rcfile path"
Specify an alternate path to the nxtvepg configuration file.
Default: \fB$HOME/.nxtvepgrc\fR on \s-1UNIX\s0,
\&\fBnxtvepg.ini\fR in the current directory on Windows.
tvsim uses this file only to get the path to a \s-1TV\s0 channel table
(you need to configure this in nxtvepg's \fI\s-1TV\s0 app interaction\fR dialog
first) and \s-1TV\s0 card configuration (the latter on Windows only).
Note the \s-1TV\s0 card index is not read from the rc/ini file, use the
option below instead.  See \*(L"\s-1GETTING\s0 \s-1STARTED\s0\*(R" for more details.
.IP "\fB\-card\fR \fIindex\fR" 4
.IX Item "-card index"
Specify which tuner card to use, if you have more than one.
Default: index 0, i.e. the \*(L"best\*(R" card in the order Brooktree Bt878,
Bt878A, Bt848, Bt849, Philips \s-1SAA7134\s0, Conexant 23881 (aka Bt811).
If you have more than one \s-1TV\s0 card with the same chip, the order
between those is undefined, but still constant (i.e. depends on
the driver, not tvsim or nxtvepg).
.IP "\fB\-help\fR" 4
.IX Item "-help"
List all available command line options.
.PP
\&\fBtvsim\fR uses the nxtvepg \s-1INI\s0 file, i.e. by default it searches for
a file named \fInxtvepg.ini\fR in the current working directory.  If this
file is located elsewhere, you need to specify the \fI\-rcfile\fR option.
Please refer to \*(L"\s-1GETTING\s0 \s-1STARTED\s0\*(R" below for configuration information.
.SH "INTERACTION FEATURES"
.IX Header "INTERACTION FEATURES"
\&\fBtvsim\fR can demonstrate all \s-1TV\s0 application interaction features
which currently are supported by \fBnxtvepg\fR:
.IP "\fBAutomatically freeing the \s-1TV\s0 card\fR" 4
.IX Item "Automatically freeing the TV card"
Windows only:
When nxtvepg is running with acquisition enabled when the \s-1TV\s0 application
is started, it automatically frees the \s-1TV\s0 card to allow the \s-1TV\s0 application
to access to the hardware.  When the \s-1TV\s0 application is stopped, nxtvepg
automatically accesses the \s-1TV\s0 card again.  This allows the user to keep
nxtvepg permanently running in the background without bothering to
remember to switch acquisition off manually before starting the
\&\s-1TV\s0 application.
.Sp
Note this feature is not required on \s-1UNIX\s0 since concurrent access to
video and \s-1VBI\s0 devices by independent processes is supported by the
drivers.
.Sp
The \s-1TV\s0 application has the possibility to \fBgrant\fR the tuner to \s-1EPG\s0,
e.g. when capturing is stopped of the \s-1TV\s0 window is minimized.  nxtvepg
will then ask the \s-1TV\s0 app to tune it's provider's channel and forward
it's teletext data.  However the driver still remains in control of the
\&\s-1TV\s0 app and can revoke the \*(L"grant\*(R" at any time without having to wait
for nxtvepg.
.IP "\fBLook-up of program info in the \s-1EPG\s0 database\fR" 4
.IX Item "Look-up of program info in the EPG database"
The \s-1TV\s0 application can pass a network name to nxtvepg to look up the title,
start and stop times and \s-1PDC\s0 theme codes of the current programme on that
network.  Usually the \s-1TV\s0 application will display that information on screen
or in a popup windows next to the live \s-1TV\s0 image.  In tvsim it's displayed
in the three text fields below that channel table.  Since Xawtv doesn't
have \s-1EPG\s0 support, there's also the option that nxtvepg by itself opens a
small popup window next to the \s-1TV\s0 image.
.Sp
Some third-party \s-1TV\s0 viewing and scheduling applications use \fI\s-1XMLTV\s0\fR
instead of this feature, but it's less efficient because the application
has to read the entire database which is not only time consuming but also
consumes a significant amount of \s-1RAM\s0, and long-running apps will also not
benefit from constant updates provided by Nextview acquisition.
.IP "\fBnxtvepg following channel changes\fR" 4
.IX Item "nxtvepg following channel changes"
When the \s-1TV\s0 channel is changed inside the \s-1TV\s0 application, nxtvepg will
follow with its cursor in the browser window, i.e. it'll set the cursor
on the program title that's currently running on that network so that
the detailed program information becomes displayed.  (Channels are
identified firstly by their name, but also by \s-1VPS/PDC\s0 which is forwarded
from the \s-1TV\s0 application to nxtvepg.)
.IP "\fBChanging channels from inside nxtvepg\fR" 4
.IX Item "Changing channels from inside nxtvepg"
When a \s-1TV\s0 application is connected to nxtvepg, there's a \fITune \s-1TV\s0\fR button
in the main window that allows to tune in the network of the program that's
currently selected in nxtvepg.  This allows the user to comfortably select
his/her favorite program inside nxtvepg.
.Sp
There's also a small context menu behind the Tune-TV button which can be
opened by clicking on it with the right mouse button.  There's commands to
start/stop capturing, muting audio and toggle channels.  Additionally the
user can send arbitrary commands to the connected \s-1TV\s0 app via user-defined
entries in nxtvepg's programme schedule context menu and reminder scripts
(by using prefix \f(CW\*(C`!xawtv!\*(C'\fR or \f(CW\*(C`!winshm!\*(C'\fR, see nxtvepg manual chapter
\&\fIContext menu extensions\fR.)  These entries may include parameters of the
currently selected programme, e.g. start time and network.
.IP "\fB\s-1EPG\s0 data acquisition while watching \s-1TV\s0\fR" 4
.IX Item "EPG data acquisition while watching TV"
Windows only:
Even while the \s-1TV\s0 card is \*(L"owned\*(R" by the \s-1TV\s0 application, it's possible
for nxtvepg to keep acquiring \s-1EPG\s0 information if it's connected to a
\&\s-1TV\s0 application that forwards incoming teletext packets on the designated
\&\s-1EPG\s0 page. 
.Sp
Note this feature is not required on \s-1UNIX\s0 for the same reasons already
mentioned above for the first item.
.SH "GETTING STARTED"
.IX Header "GETTING STARTED"
The software is called a \*(L"simulator\*(R" because it doesn't display a \s-1TV\s0
image.  But still it does read in a channel table and tune in the
respective \s-1TV\s0 channels when they are selected in the channel table;
this is required to demonstrate forwarding of \s-1VPS/PDC\s0 and \s-1EPG\s0 packets.
.PP
tvsim does not have its own rc/INI file, instead it uses the nxtvepg
configuration file.  Hence you should configure nxtvepg first before using
tvsim.  Please refer to the nxtvepg manual, section \fI\s-1GETTING\s0 \s-1STARTED\s0\fR
for detailed documentation of the initial configuration process.
tvsim only uses the configuration settings of the \fI\s-1TV\s0 card input\fR
and \fI\s-1TV\s0 app. interaction\fR dialogs, with the exception of the
\&\s-1TV\s0 card index.
.PP
If your \s-1TV\s0 application's channel table format is not supported by
nxtvepg and you don't have any of the supported freeware \s-1TV\s0 applications,
you can set up a minimal channel table manually.  The simplest format
is that of the DScaler channel table; so create a file named
\&\fIprogram.txt\fR somewhere with the following format:
.PP
.Vb 4
\&   Name: First Channel
\&   Freq2: 2020
\&   Name: Second Channel
\&   Freq2: 2132
.Ve
.PP
where you replace \*(L"First Channel\*(R" etc. with the actual channel names and
the numbers with the respective \s-1TV\s0 tuner frequencies in MHz times 16
(i.e. 2020 means tuner frequency 126.25 MHz). Then open the
\&\fI\s-1TV\s0 app. interaction\fR dialog in nxtvepg, choose \s-1TV\s0 app. name \fIDScaler\fR
and specify the path to the channel table you've just creatd. Then quit
the dialog with Ok and start tvsim (you don't need to quit nxtvepg).
Your channels should appear in the tvsim channel table.
.SH "FILES"
.IX Header "FILES"
.IP "\fB$HOME/.nxtvepgrc\fR" 4
.IX Item "$HOME/.nxtvepgrc"
Configuration file on \s-1UNIX\s0 systems. Per default it'is expected in your
home directory; for more details see below and \*(L"\s-1GETTING\s0 \s-1STARTED\s0\*(R".
.IP "\fBnxtvepg.ini\fR" 4
.IX Item "nxtvepg.ini"
Windows configuration file from which \s-1TV\s0 card setup and \s-1TV\s0 application interaction
settings are read.  By default it is expected in the working directory,
but a different path and file name can be specified with the \fB\-rcfile\fR
option.  tvsim never writes to this file;  configuration changes have
to be made with nxtvepg.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Please refer to the manual of \fBnxtvepg\fR for information on \s-1TV\s0 card and
\&\s-1TV\s0 application interaction configuration.  See also the manuals for
\&\fBvbirec\fR and \fBvbiplay\fR for further debugging possibilities.
.PP
Please refer to the homepage of nxtvepg on the Internet for up-to-date
information which protocols and \s-1TV\s0 applications are currently supported.
You'll also find links to the respective applications homepages.  See
\&\fIAbout\fR in the \fIHelp\fR menu for a link to the nxtvepg homepage.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
Under Windows there's a risk of system crash (\*(L"blue screen\*(R") when the
application is terminated by force, e.g. via the task manager. This
is unavoidable because in this case there's no chance to stop the
driver and hence the \s-1TV\s0 card continues to capure data into \s-1RAM\s0.
In normal operation this should be very unlikely because all software
exceptions (e.g. page faults) and shutdown messages are caught and the
driver then stopped before the exit.
.SH "AUTHOR"
.IX Header "AUTHOR"
Th. \*(L"Tom\*(R" Zoerner, Nuremberg, Germany.
.PP
Email: tomzo (at) users (dot) sourceforge (dot) net
.PP
Thanks to \fIe\-nek\fR for reviewing the design of the Windows communication
protocol, alpha testing and most importantly for being the first one to
implement support specifically for interaction between nxtvepg and a
\&\s-1TV\s0 application (the Xawtv solution predates K!TV, however it was based
on already existing remote control mechanisms, i.e. no changes were
made to Xawtv.)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2002,2004 by Th. Zoerner.
All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License Version 2 as
published by the Free Software Foundation, e.g. at
http://www.fsf.org/
.PP
This program is distributed in the hope that it will be useful, but
\&\fB\s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0\fR; without even the implied warranty of
merchantability or fitness for a particular purpose. See the
file \fI\s-1COPYRIGHT\s0\fR for more details.