# ---------------------------------------------------------------------------
#
#  TV application interaction simulator online manual
#
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License Version 2 as
#  published by the Free Software Foundation. You find a copy of this
#  license in the file COPYRIGHT in the root directory of this release.
#
#  THIS PROGRAM IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL,
#  BUT WITHOUT ANY WARRANTY; WITHOUT EVEN THE IMPLIED WARRANTY OF
#  MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#
#  Description:
#
#    User's documentation in Perl "POD" format. The content is
#    converted into various other formats by use of different scripts:
#    UNIX manpage by pod2man; HTML web page by pod2html (needs manual
#    adjustments) and the online help by a self-made script. The releases
#    should contain the converted files, so that the user is not forced
#    to install Perl.
#
#  Author: Tom Zoerner
#
# $Id: tvsim.pod,v 1.9 2004/03/23 15:59:54 tom Exp tom $
# ---------------------------------------------------------------------------

=head1 NAME

tvsim - TV application interaction simulator

=head1 SYNOPSIS

B<tvsim> S<[ options ]>

=head1 DESCRIPTION

B<tvsim>
is a demo application that shows in which ways nxtvepg can cooperate
with TV applications.
It's also a reference implementation of the communication protocols
and offers most of the source code (under the GPL license) that would
be required to add EPG support to a TV application.  If you want to
add nxtvepg to a TV application, it's recommended to start with the
code of tvsim's source modules, remove everthing you don't need (esp.
the Tcl/Tk GUI and support for all but one protocols), put it in a
library and link it to your TV app.

In the current version two protocols are supported: On UNIX an X11 atoms
based protocol which allows interaction with I<xawtv> and I<xawdecode>.
On Windows a shared memory based protocol which allows interaction
with I<K!TV>.

=head1 OPTIONS

Summary of command line options (it's a sub-set of the options
supported by nxtvepg):

=over 4

=item B<-geometry> I<geometry>

Specifies the position of the main window, e.g.  B<-geometry -0+0>
to put the main window in the upper right corner of the visible screen.
The size of the window cannot be changed.

=item B<-iconic>

Start with the main window iconified (i.e. minimized).

=item B<-rcfile> I<path>

Specify an alternate path to the nxtvepg configuration file.
Default: B<$HOME/.nxtvepgrc> on UNIX,
B<nxtvepg.ini> in the current directory on Windows.
tvsim uses this file only to get the path to a TV channel table
(you need to configure this in nxtvepg's I<TV app interaction> dialog
first) and TV card configuration (the latter on Windows only).
Note the TV card index is not read from the rc/ini file, use the
option below instead.  See L<"GETTING STARTED"> for more details.

=item B<-card> I<index>

Specify which tuner card to use, if you have more than one.
Default: index 0, i.e. the "best" card in the order Brooktree Bt878,
Bt878A, Bt848, Bt849, Philips SAA7134, Conexant 23881 (aka Bt811).
If you have more than one TV card with the same chip, the order
between those is undefined, but still constant (i.e. depends on
the driver, not tvsim or nxtvepg).

=item B<-help>

List all available command line options.

=back

B<tvsim> uses the nxtvepg INI file, i.e. by default it searches for
a file named I<nxtvepg.ini> in the current working directory.  If this
file is located elsewhere, you need to specify the I<-rcfile> option.
Please refer to L<"GETTING STARTED"> below for configuration information.


=head1 INTERACTION FEATURES

B<tvsim> can demonstrate all TV application interaction features
which currently are supported by B<nxtvepg>:

=over 4

=item B<Automatically freeing the TV card>

Windows only:
When nxtvepg is running with acquisition enabled when the TV application
is started, it automatically frees the TV card to allow the TV application
to access to the hardware.  When the TV application is stopped, nxtvepg
automatically accesses the TV 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
TV application.

Note this feature is not required on UNIX since concurrent access to
video and VBI devices by independent processes is supported by the
drivers.

The TV application has the possibility to B<grant> the tuner to EPG,
e.g. when capturing is stopped of the TV window is minimized.  nxtvepg
will then ask the TV app to tune it's provider's channel and forward
it's teletext data.  However the driver still remains in control of the
TV app and can revoke the "grant" at any time without having to wait
for nxtvepg.

=item B<Look-up of program info in the EPG database>

The TV application can pass a network name to nxtvepg to look up the title,
start and stop times and PDC theme codes of the current programme on that
network.  Usually the TV application will display that information on screen
or in a popup windows next to the live TV image.  In tvsim it's displayed
in the three text fields below that channel table.  Since Xawtv doesn't
have EPG support, there's also the option that nxtvepg by itself opens a
small popup window next to the TV image.

Some third-party TV viewing and scheduling applications use I<XMLTV>
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 RAM, and long-running apps will also not
benefit from constant updates provided by Nextview acquisition.

=item B<nxtvepg following channel changes>

When the TV channel is changed inside the TV 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 VPS/PDC which is forwarded
from the TV application to nxtvepg.)

=item B<Changing channels from inside nxtvepg>

When a TV application is connected to nxtvepg, there's a I<Tune TV> 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.

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 TV app via user-defined
entries in nxtvepg's programme schedule context menu and reminder scripts
(by using prefix C<!xawtv!> or C<!winshm!>, see nxtvepg manual chapter
I<Context menu extensions>.)  These entries may include parameters of the
currently selected programme, e.g. start time and network.


=item B<EPG data acquisition while watching TV>

Windows only:
Even while the TV card is "owned" by the TV application, it's possible
for nxtvepg to keep acquiring EPG information if it's connected to a
TV application that forwards incoming teletext packets on the designated
EPG page. 

Note this feature is not required on UNIX for the same reasons already
mentioned above for the first item.

=back


=head1 GETTING STARTED

The software is called a "simulator" because it doesn't display a TV
image.  But still it does read in a channel table and tune in the
respective TV channels when they are selected in the channel table;
this is required to demonstrate forwarding of VPS/PDC and EPG packets.

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 I<GETTING STARTED>
for detailed documentation of the initial configuration process.
tvsim only uses the configuration settings of the I<TV card input>
and I<TV app. interaction> dialogs, with the exception of the
TV card index.

If your TV application's channel table format is not supported by
nxtvepg and you don't have any of the supported freeware TV 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
I<program.txt> somewhere with the following format:

   Name: First Channel
   Freq2: 2020
   Name: Second Channel
   Freq2: 2132

where you replace "First Channel" etc. with the actual channel names and
the numbers with the respective TV tuner frequencies in MHz times 16
(i.e. 2020 means tuner frequency 126.25 MHz). Then open the
I<TV app. interaction> dialog in nxtvepg, choose TV app. name I<DScaler>
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.


=head1 FILES

=over 4

=item B<$HOME/.nxtvepgrc>

Configuration file on UNIX systems. Per default it'is expected in your
home directory; for more details see below and L<"GETTING STARTED">.

=item B<nxtvepg.ini>

Windows configuration file from which TV card setup and TV 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 B<-rcfile>
option.  tvsim never writes to this file;  configuration changes have
to be made with nxtvepg.

=back


=head1 SEE ALSO

Please refer to the manual of B<nxtvepg> for information on TV card and
TV application interaction configuration.  See also the manuals for
B<vbirec> and B<vbiplay> for further debugging possibilities.

Please refer to the homepage of nxtvepg on the Internet for up-to-date
information which protocols and TV applications are currently supported.
You'll also find links to the respective applications homepages.  See
I<About> in the I<Help> menu for a link to the nxtvepg homepage.


=head1 KNOWN BUGS

Under Windows there's a risk of system crash ("blue screen") 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 TV card continues to capure data into RAM.
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.


=head1 AUTHOR

Th. "Tom" Zoerner, Nuremberg, Germany.

Email: tomzo (at) users (dot) sourceforge (dot) net

Thanks to I<e-nek> 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
TV 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.)


=head1 COPYRIGHT

Copyright (C) 2002,2004 by Th. Zoerner.
All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License Version 2 as
published by the Free Software Foundation, e.g. at
http://www.fsf.org/

This program is distributed in the hope that it will be useful, but
B<WITHOUT ANY WARRANTY>; without even the implied warranty of
merchantability or fitness for a particular purpose. See the
file F<COPYRIGHT> for more details.

