# ---------------------------------------------------------------------------
#
#  VBI recorder documentation
#
#  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: vbirec.pod,v 1.10 2004/12/12 15:56:40 tom Exp tom $
# ---------------------------------------------------------------------------

=head1 NAME

vbirec - TV application interaction monitor and EPG recorder


=head1 SYNOPSIS

B<vbirec> S<[ options ]>


=head1 DESCRIPTION

B<vbirec> is a tool that helps in debugging TV application's interaction
with nxtvepg.  B<vbirec> takes the place of nxtvepg in the communication.
It monitors the shared memory which is used for communication with the
TV app. and displays all TV app controlled values in it's main window.


=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<-card> I<index>

UNIX only: Specify which tuner card to use, if you have more than one,
for details see nxtvepg manual.  Note this option is not supported on
Windows because there the TV application is forwarding teletext data;
on UNIX vbirec and nxtvepg are accessing the driver directly.

=item B<-help>

List all available command line options.

=back

=head1 MONITORING VBI RECEPTION

The following shared memory elements are displayed
and updated every 500 millyseconds:

=over 4

=item B<TTX pkg count>

The total number of teletext packets the TV app. has received since the
last channel change.

=item B<TTX pkg per frame avg.>

A running average of the number of VBI lines containing teletext packets
per video frame.

=item B<VPS lines count>

The total number of VPS lines the TV app. has received since the
last channel change.  For networks that transmit VPS there should
be one VPS line in each frame.

=item B<EPG page count>

The number or EPG pages since the last channel change, i.e. the number
of teletext packets with packet address zero on the designated EPG
teletext page.

=item B<EPG packet count>

The total number or teletext packets on the designated EPG teletext page
since the last channel change.

=item B<VPS CNI and PIL>

The last received and confirmed VPS network and program identifiers.
VPS is only used by German, Austrian and Swiss networks.

=item B<PDC CNI and PIL>

The last received and confirmed PDC (teletext packet 8/30/2) network
and program identifiers.  If the network transmits only a network
identifier value of zero, but does include a status display text
(which usually contains channel name and sometimes also the title
of the current programme) it's displayed here instead.
VPS is mainly used by British and French networks.

=item B<Packet 8/30/1>

The last received and confirmed packet 8/30/1 network identifier.
If the network transmits only a network identifier value of zero
but does include a status display text it's displayed here instead.

=item B<EPG teletext page no>

The teletext page number on which EPG is tranmitted according to the
provider.  Note: the default page is 0x1DF; other page numbers can be
specified in the teletext magazine inventory page of each magazine.

=item B<Teletext header>

The text part of the last received teletext packet with address 0.
Usually the text contains the teletext page number, network name,
clock and date.  This element is provided here mainly to allow detecting
which TV network was tuned by the TV application.

=item B<Network by VPS/PDC/NI>

A human readable network identification derived from the VPS, PDC or
P8/30/2 CNI codes (in this order, if several alternatives are available).

=back 4


=head1 MONITORING TV APP CONTROLS

The following shared memory elements are displayed
and updated whenever updates are signalled by the TV application:

=over 4

=item B<TV app. channel name>

The TV application's station name for the currently tuned channel.
This element should be updated after ever channel change.

=item B<TV app. channel CNI>

The TV application's numerical network identifier for the currenlty
tuned channel.  If unavailable it should be set to zero.

=item B<TV app. input source>

The TV application's current video input source (0=TV tuner, 1=composite,
2=S-Video or Composite #2).

=item B<TV app. tuner freq.>

The current TV tuner frequency from which VBI data is forwarded. This
value must be updated after every channel change.

=item B<TV app. grants tuner>

Boolean flag that indicates if the TV application currently honors
the EPG application's input source and tuner frequency requests.
The TV application should grant the tuner when video capturing is
disabled of the TV window minimized or completely obscured by other
windows.

=back 4


=head1 TV APP INTERACTION

The following dialog section allows to send requests to a connected
TV application.

=over 4

=item B<Send EPG Information to OSD>

You can enter a programme title, start time, duration and date offset
which is sent to the TV app when you press the I<Send> button.
The TV app should display the data on-screen (OSD) 
When you don't enter a time and date, I<vbirec> invents start and
stop times by itself: start is the last full hour, duration 60 minutes.

=item B<Send TV Control Command>

You can enter a command and press I<Send> to pass it to the TV app.
Command arguments are separated by blanks (there's currently no way
to escape possible blanks inside command arguments)

Which commands are supported depends on the TV application.  At minimum
they should support command "setstation" with a network name as argument.
A list of commands which are used by nxtvepg is available in the
drop-down menu below the command entry field.

=back 4


=head1 EPG RECORDING

Packets received on the designated EPG teletext page can be stored
into a file for later playback by B<vbiplay>.  The intended use is
to allow me debugging decoding errors, e.g. for providers that I
cannot receive at my location.

The name of the output file is specified by the entry field at the
bottom of the window.  The file is created as soon as recording is
enabled by checking the I<Enable teletext recorder> button.


=head1 FILES

=over 4

=item B<ttx.dat>

Default output file name for recorded teletext packets.

=item B<vbi_map.dat>

This hidden file is used to set up shared memory to allow information
exchange between vbirec and an attached TV application.  It's
automatically removed when vbirec terminates and should never be
accessed (i.e. being written to or removed) by external applications.

=back


=head1 SEE ALSO

See also the manuals for B<nxtvepg>, B<tvsim> and B<vbiplay>.


=head1 AUTHOR

Th. "Tom" Zoerner, Nuremberg, Germany.

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


=head1 COPYRIGHT

Copyright (C) 2002,2004 by Th. 'Tom' 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.

