nxtvepg manual

This is the manual page for release 3.0.0 of the nxtvepg software package.

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• GETTING STARTED
  • Configuring the Teletext EPG Grabber
  • Configuring TV card input
  • Configuring a TV application
• BASIC BROWSING
• TELETEXT EPG GRABBER
  • Using Teletext EPG
  • Acquisition modes
• STATISTICS
  • Status line
  • Timescale popup window
  • Database statistics
  • Teletext grabber statistics
• MERGED DATABASES
• FILTERING
  • Filter Types
  • Inverting filters
• FILTER SHORTCUTS
  • Editing Filter Shortcuts
  • Filter Masks
  • Shortcut combination modes
  • Shortcut update dialog
• COMPOSITE ATTRIBUTES
• REMINDERS
  • Edit reminder list
  • Reminder group configuration
  • Reminder Messages
• CONTEXT MENU
• CONTROL MENU
  • Load XMLTV file
  • Merge XMLTV files
  • Load Teletext EPG
  • Enable acquisition
  • Connect to acq. daemon
  • View statistics/timescales
  • Export as text
  • Export as XMLTV
  • Export as HTML
  • Quit
• CONFIGURE MENU
  • Teletext grabber
  • TV channel scan
  • TV card input
  • Client/Server
  • TV application interaction
  • Select attributes
  • Attribute composition
  • Select networks
  • Network names
  • Context menu configuration
  • Themes language
  • Show/Hide
  • List layout
• FILES
  • Files used on UNIX systems
  • Files used on Windows systems
• AUTHOR
• COPYRIGHT

NAME

nxtvepg - Browsing EPG data in XMLTV files and grabbing EPG from teletext

SYNOPSIS

nxtvepg [ options ] [ XMLTV_files ... ]

nxtvepgd [ daemon options ]

DESCRIPTION

nxtvepg is a X11 and Win32 application for browsing TV programme schedules (EPG) loaded from files in XMLTV format. Using a TV capture card, TV schedules can additionally be grabbed from teletext pages.

nxtvepgd is a stripped-down version of nxtvepg which only performs EPG data acquisition from a TV capture card as a background daemon process. EPG data is written to files in XMLTV format, which can later be used by the nxtvepg GUI or any other application supporting XMLTV.

New users of the software are encouraged to start reading at chapter "GETTING STARTED" for setting up EPG acquisition from teletext. If you do not plan to use that feature, skip forward to chapter "BASIC BROWSING".

OPTIONS

The XMLTV_files ... parameters on the command line can be one or more files in XMLTV format. If more than one file is given, the contents are merged in the way described for "MERGED DATABASES". The EPG data in the respective files will then be loaded and shown in the GUI.

Summary of command line options:

-display display

UNIX only: The display on which the user interface will be placed, for example localhost:0.0. Default: taken from environment variable DISPLAY. For more info see the X manual page section Display Names

-tvdisplay display

UNIX only: The display on which the TV application window is searched, e.g. on a remote host or different screen on a station with multiple monitors. Default: same as the main window's display.

-geometry geometry

Specifies the position of the main window, e.g. -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.

-iconic

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

For M$ Windows users this option may be esp. helpful when nxtvepg is started from inside the Auto start group and Hide on minimize is enabled: nxtvepg then will start almost invisibly in the background, only with an icon in the system tray of the task bar (see also "CONFIGURE MENU", section "Show/Hide").

-rcfile path

Specify an alternate configuration file. Default: on UNIX $HOME/.config/nxtvepg/nxtvepgrc, on Windows nxtvepg.ini in the current directory.

-dbdir directory

Specify an alternate directory for XMLTV files written by the Teletext EPG grabber. Default: On UNIX $HOME/.cache/nxtvepg, on Windows the current directory.

Note that the database management is not equipped for concurrent writing. Therefore, when running multiple instances of nxtvepg concurrently, use this option for selecting different storage directories.

If you are using an acquisition daemon, the browser must be configured to use the same directory as the daemon. If the daemon is running on a different host, you need to mount the remote directory, e.g. via NFS.

-card index

Specify which TV card hardware to use, if you have more than card. Default: index 0. On Linux the given index is appended to the device names, i.e. /dev/vbi and /dev/video (see also "FILES"). On Windows index "n" means the n-th card found while scanning the PCI bus for cards with a supported capture chip (e.g. Brooktree Bt878, Bt878A, Bt848, Bt849, Philips SAA7134, Conexant 23881). If you have more than one TV card with the same chip, the order between those is undefined, but still constant (i.e. the order is determined by the driver, not nxtvepg)

-noacq

Start with acquisition disabled. The acquisition can still be started later from the Control menu (see "CONTROL MENU: Enable acquisition").

-daemon

Start without graphical user interface and silently perform acquisition "in the background." This option is implied when running nxtvepgd. (The daemon-only executable is slightly more efficient since it's smaller and uses less libraries than the GUI executable and hence needs less memory.)

If no other options are given the same acquisition mode as configured with the GUI will be used. The -daemon option cannot be combined with -noacq, -remctrl, or other GUI-specific options.

The daemon always creates a named socket in the /tmp directory (UNIX only) plus optionally a TCP/IP socket to allow connects by browser processes. While connected, the browser is notified whenever the teletext EPG grabber updates an XMLTV file; if left unconnected, the browser listing might remain incomplete or outdated.

It's important to note that the browser must use the same database directory (see option -dbdir), because the daemon forwards only deltas to the database files stored in that directory. For more details see "CONFIGURE MENU", section "Client/Server".

UNIX warning: for security reasons it's depreciated to run the daemon with root privileges, because nxtvepg has not been reviewed yet for possible exploits. If you want to start the daemon already during system startup, you should use su(1). Also note that you'll probably need to specify -rcfile and -dbdir because the $HOME environment variable might not be (correctly) defined. Example:

su nobody -c "/usr/local/bin/nxtvepg -daemon \
              -rcfile /usr/local/etc/nxtvepgrc"

For terminating the daemon process, see the -daemonstop option below. Alternatively you can stop the daemon via the graphical user interface by disabling enable acquisition in the control menu.

-daemonstop

With this option, a background acquisition process is searched and terminated if found; then the program exits. Note you need permission to send signals to the daemon process to be able to stop it (i.e. it must run with the same user ID). This option is meant to allow controlling acquisition by scripts which start and stop acquisition automatically after a given time.

Note if the daemon is running on the same host and uid, it can also be stopped by deselecting Enable acquisition in the Control menu while being connected to the daemon. For more details see "CONTROL MENU" and "FILES".

-daemonquery

With this option, the acquisition status of a running nxtvepg daemon is retrieved and printed to the terminal. This can be used to determine the current status without use of the graphical user interface. This can also be used by shell scripts to control the acquisition process. The output is written to stdout unless you redirect it into a file or pipe it into another program. See also option -outfile. Possible errors are reported to stderr as usual.

Note you can query the daemon directly without use of a nxtvepg client by connecting to the host and port where the daemon accepts client connections and send the string "\x00\x11\x00\x00ACQSTAT". The daemon will reply with a 4-byte header followed by a variable-length string: The first two header bytes specify the message length including header in beg-endian binary format; the next two bytes are two and zero; the remaining bytes are the message text. Example script implemented in the Tcl programming language:

#!/usr/bin/tclsh
if {[catch {set sock_fd [socket localhost 7658]} err] == 0} {
   fconfigure $sock_fd -buffering none -encoding binary
   puts -nonewline $sock_fd [binary format Scxa7 11 0 ACQSTAT]
   set line [read $sock_fd 4]
   binary scan $line "Scx" len type
   set line [read $sock_fd [expr {$len - 4}]]
   binary scan $line "a*" msg
   puts -nonewline $msg
} else {
   puts stderr "Failed to connect to daemon ($err)"
}

-nodetach

UNIX only: In daemon mode this option prevents the process actually making itself a daemon, i.e. it doesn't fork and stays connected to the terminal. Also all log messages starting with level warning are sent to standard error out (e.g. configuration errors that lead to an immediate exit). This mode is intended for debugging purposes only.

-acqpassive

In daemon mode this option overrides the acquisition mode setting in the configuration file and forces acquisition into passive mode (see description of acquisition modes in chapter "TELETEXT EPG GRABBER"). The configuration file is not changed, so that you can use different acquisition strategies for daemon and GUI.

-acqonce phase

In daemon mode this option will automatically stop acquisition and terminate the daemon after the given phase has been completed. Phases are as defined in "TELETEXT EPG GRABBER", namely now or full.

If you want to run another program from inside a script after nxtvepg has finished, use the -nodetach option (UNIX only) Then the shell which is processing the script will usually wait for nxtvepg to terminate before starting the next command. On Windows there's no simple way to achieve this (because non-console applications are always run in the background), so you need to use a script language which supports instructions which wait until a running program (namely nxtvepg) has finished.

-dump mode

When started with this argument, nxtvepg will only export the entire programme database, then exit. An XML file has to be specified on the command line, as this data will be exported.

To export the database in XML format, use keyword xml as mode. In this case the last time format which was used via the XMLTV export dialog is used. To export the database in a specific format, use xml5utc or xml5ltz. For more details see "CONTROL MENU: Export as XMLTV". Note by default this mode exports the complete database, including already expired programmes and networks which are suppressed in the GUI. To filter the output, use option -epgquery.

To export programme data into a HTML document, use keyword html as mode. The same options as configured in the HTML export dialog are applied (unless you are using the daemon executable nxtvepgd to perform the export.) For details see "CONTROL MENU: Export as HTML". The number of exported programmes can be limited by adding a number after the keyword, separated by a colon (e.g. -dump html:50.) However the format of the programme list is currently not configurable via command line options.

To export the database into a plain text file (e.g. for import into an SQL database) three mode keywords are supported: pi to dump programmes (i.e. the complete TV schedules), ai to dump the content provider's network table, themes to dump the provider's theme categories table. For more details see "CONTROL MENU: Export as text".

The output is written to stdout unless you redirect it into a file or pipe it into another program. See also option -outfile

-outfile path

This option allows to redirect output from -dump or any other modes which print to stdout by default. It also works in normal operation modes, but the created file will be empty. nxtvepg will abort if the specified file already exists to avoid inadvertently overwriting other files. If you're using the option inside a script or batch file you should add a command to remove the target file before invoking nxtvepg.

This option is especially helpful for M$ Windows users, since output written to stdout is discarded by the operating system because nxtvepg is not a "console application". This means for example, if output of the above -dump mode is not to be discarded, you must either use this option or redirect output as explained below.

Note: instead of using this option you can also redirect output with the ">" or "|" operators in UNIX shells or under M$ Windows at the MS-DOS command prompt. For example you could use either of the following:

nxtvepg -dump ai tv.xml > networks.txt
nxtvepg -dump ai tv.xml | more

to either write the network table of XMLTV file "tv.xml" into a file named networks.txt, or pipe it to the paging program "more" respectively.

-epgquery FILTER=option

This option can be used in combination with -dump to limit the amount of programmes which is exported. The option can be used multiple times to combine different filters. The available filter types are a subset of those which are available in the graphical interface:

EXPIRE=NOW or EXPIRE=delay or EXPIRE=time

This command with parameter value NOW will only list programmes which are currently running or starting in the future. In other words, programmes which have already finished are suppressed. Alternatively, the parameter can be a numeric value which specifies a number of minutes up to which the stop time may be in the past; alternatively the value may specify a date and time in the format YYYY-MM-DD.HH:MM or just a time in format HH:MM. The latter always refers to the current date.

PROGIDX=index_range

This command is another possibility to restrict the listing to unexpired programmes. With this command for each network the programmes with the given index or within the given index range are listed. The index zero refers to the currently running programme on each channel. (When none is currently running, index 1 refers to the one which is next up.)

NETNAME=name

This command will only list programmes running on a network with the given name. To allow for multiple networks, use separate -epgquery options for each network. The name has to be specified exactly as it appears in the XMLTV file. Unknown names are silently ignored.

NETIDX=index_list

This command will only list programmes with the given index in the channel table (i.e. zero refers to the first programme in the table, 1 to the second and so on.) Multiple indices can be given when separated by commas, or as a range separated by a dash (e.g. NETIDX=0,2,5-10)

CHN_ID=id_string

This command will only list programmes with the given channel identifier as specified in <channel id="..."> in the XMLTV file (e.g. CHN_ID=ard.de for the German "ARD".) Note the identifier name comparison is case-sensitive. To allow for multiple networks, use separate -epgquery options for each network.

NETWOP_PRE

This command restricts networks to the same list you have configured for the nxtvepg main application. This command has no parameters and cannot be combined with any other network selection commands.

THEME=name

This command will only list programmes labeled with the given theme category. The theme name should be specified exactly as it appears in the XMLTV input file. Unknown names are silently ignored.

TITLE=text

This command will only list programmes with the given text in the programme title. Case is ignored. If this option is used more than once, all programmes with titles matching at least one of the given text strings are listed.

TITLE_WHOLE=text

This command will only list programmes which have the exact given text as title. Case is ignored. If this option is used more than once, all programmes with titles matching at least one of the given text strings are listed.

TEXT=text

This command searches the given text anywhere in the title or description. Case is ignored. If this option is used more than once, all programmes matching at least one of the given text strings are listed.

START=date or START=date1-date2

This command will list only programmes starting at the given time or in the given time range respectively. Times can be specified as combined date and time in format YYYY-MM-DD.HH:MM or as just a time in format HH:MM. The latter always refers to the current date. (Example: -epgquery start=22:00-23:00)

DURATION=nnn or DURATION=nnn-mmm

This command will only list programmes with a duration in the given numerical range, or with the exact given duration, if "-mmm" is omitted. In this context, "duration" means the difference of start and stop times in minutes (e.g. "15:00 - 16:00" has a duration of 60 minutes.)

PAR_RAT=age

This command will only list programmes which are rated as OK for a person of the given age, or older. For example PAR_RAT=12 will list programmes rated "G", "6", "12". Use -epgquery INVERT in addition to get the opposite behavior (i.e. in the earlier example: programmes not ok for age 12, which equals age 16 and up.) Note programmes without parental rating are generally excluded when this option is used.

EDIT_RAT=rating

This command will only list programmes with the given editorial rating or a higher rating. The range of ratings depends on the content provider. The maximum range is 1 to 7. Note programmes without editorial rating are generally excluded when this option is used.

FEATURES=keywords

This command will only list programmes with all the features indicated by the given keyword list. The following keywords are accepted: Relating to audio: MONO, STEREO, 2CHAN (multi-lingual), SURROUND; relating to screen aspect ratios: FULL (4:3), WIDE (16:9), PALPLUS; relating to transmission: ANALOG, DIGITAL; relating to encryption: UNCRYPT, CRYPT; relating to repetitions or live broadcast: LIVE, NEW, REPEAT; relating to teletext subtitles: SUBTITLES.

When this command is used multiple times, the different feature queries are logically ORed, meaning all programmes which match all features given by one of the commands will be listed. (Example: -epgquery FEATURES=stereo,wide -epgquery FEATURES=surround,wide will list all programmes in 16:9 aspect ratio with either stereo or surround sound.)

INVERT

This command will only list programmes which do not match any of the filters given with -epgquery options. See also "FILTERING".

Example:

nxtvepg -dump html tv.xml -outfile tv.html \
          -epgquery TITLE=Tagesschau -epgquery expire=NOW

-remctrl command

This option can be used to remote control an other, previously started GUI instance of nxtvepg, i.e. to send the given command to the other process and then exit.

The following commands are available: quit to terminate the other nxtvepg process; iconify to minimize the window; deiconify to undo a previous minimization; raise to deiconify the other window and to bring it to the top (in case it's obscured by other windows); acqon to start acquisition; acqoff to stop acquisition.

-clock mode

When started with this argument, nxtvepg will acquire the current date and time from teletext and then terminate. The first channel in your selected TV application's channel table is used as a source.

Important restriction: nxtvepg is able to retrieve the clock only from channels where the so-called teletext packet 8/30/1 is transmitted, which contains date, time and local time zone offset in a binary format. nxtvepg will never attempt to retrieve times from teletext header lines.

With mode print the date and time will be read and printed. The output is written to stdout unless you redirect it into a file or pipe it into another program. See option -outfile for details.

With mode set the time is set as system time, provided the calling user has the necessary privileges (e.g. you'd need to be root on UNIX; since it's depreciated to run nxtvepg with root privileges, it's recommended to first print the time into a file and then pass it to date).

UNIX users should also note that the set mode does not update the battery powered hardware clock (aka Real Time Clock RTC), so the correction will probably be lost with the next reboot. To update your RTC, call hwclock --systohc or your operating system's equivalent after nxtvepg. Some Linux distributions automatically take care of this during shutdown.

-help

List all available command line options.

If you specify XMLTV file names on the command lines, these have to follow after all option values.

Note to Windows users: all these options - unless otherwise noted - are available in the Win32 version too. You can supply the options either from a "MS-DOS" command prompt or batch file, or by appending them to the executable in a shortcut definition.

GETTING STARTED

This manual describes all features of nxtvepg in detail. You do not have to read all of it at once to operate the software.

If you plan to use nxtvepg only for displaying contents of XMLTV files, you can skip the remainder of this chapter, but it's recommended to skim at least through "BASIC BROWSING" and "FILTERING".

The following descriptions will provide description of minimal steps needed to get the Teletext EPG grabber up and running so that you can start browsing TV schedules. Ideally this should just take a few clicks in the right places.

For a detailed description of Teletext grabber configuration and its inner working, see chapter "TELETEXT EPG GRABBER".

Configuring the Teletext EPG Grabber

By default, the Teletext EPG Grabber is disabled, because it needs to be told where to find the table of TV channels that it should tune for receiving Teletext pages. This is done via the Teletext Grabber command in the Configure menu.

For enabling the grabber, you need at minimum check the button at the top of the dialog. Afterward, select a TV-application name within the TV channel table box. nxtvepg will then try to automatically find the path of the channel table, where your TV application stores its channel table. In case the path is not filled in automatically, or is not filled correctly, please click the folder button next to the Path entry field and select the path manually. Use the Test button to check if nxtvepg can parse the file successfully.

Not mandatory, but highly recommended is checking additionally the value of Number of TV channels to grab in the Teletext options box. The grabber will receive only from that number of TV channels in the configured TV channel table (not counting radio channels). Assuming you ordered your channel table so that the channels most interesting to you come first, you can use this setting to limit grabbing to those channels. This avoids wasting time on other channels. Notably, the setting also determines the number of channels that are loaded into the browser automatically via the Load Teletext EPG command on the Control menu.

See "CONFIGURE MENU" section "Teletext grabber" for details about the other options in this configuration dialog.

When leaving the dialog with the Ok button, the Teletext grabber will start receiving data immediately (unless you unchecked the Start acquisition automatically button). You'll see a note about this in the status line at the bottom of the main window. If you have not loaded an XMLTV file yet, output from the grabber should show up after about two minutes. If not, see the following chapter, or check if the first channels listed in your TV channel table do transmit teletext and have their TV schedule tables at the default range 301-399 (if not, change the page range via the configuration dialog).

Configuring TV card input

The Teletext EPG grabber is using your TV capture card for receiving teletext. By default, the grabber uses the first card the operating system reports and from that, the first input the card driver reports. If you have a only single card, and your card has a single antenna connector, then this will be fine. Otherwise your results may vary, so you should check the settings in the TV card input dialog in the Configure menu.

At the top of the dialog window, the card is selected. The offered choices are the TV card detected by the operating system and its drivers. Fist check that the radiobuttons show the correct card type: Digital TV for DVB, or Analog TV for PAL/SECAM. Then the name of your capture card should be shown at the top. If you have multiple digital or analog card you can select which one to use via the drop-down menu.

After the correct card is selected, check that video source is set to use the TV antenna. Drivers may call this by other names, such as "TV tuner" or "RF input". (See section TV card input in the "CONFIGURE MENU" chapter for more details.) Afterwards close the dialog with the Ok button. If still running, acquisition should automatically switch to the new TV card parameters. If the status line shows "Acquisition disabled", then enable it via the Enable acquisition command in the Control menu.

Configuring a TV application

nxtvepg can cooperate in the following ways with TV applications:

• Loading the TV application's channel table allows easily synchronizing channel names shown in the browser with the ones you configured in your TV application: This can be achieved via the Network name dialog in the Configure menu (see "CONFIGURE MENU", section "Network names").

  Note if you are using the Teletext EPG grabber as source for TV schedules, then channels names in EPG are already identical to that of your TV application, so that use of the Network name dialog is moot.

• Interaction between nxtvepg and the TV application, to provide you with convenience features like an on-screen display of the current programme title after channel changes, changing the channel from inside nxtvepg with the TuneTV button, and background EPG data acquisition while you're watching TV.

The first one is a passive feature, i.e. only nxtvepg needs to be adapted to the respective TV applications. The second one however requires cooperation of both sides. For this reason the number of TV applications for which the passive features are supported will always be much larger.

Regarding the second feature, i.e. the "active" one: On Windows the interaction features are currently only supported by K!TV (an analog TV viewer). On UNIX active features are unfortunately only supported for old analog TV applications such as xawtv, but not for any DVB applications. You can check the list of supported applications via the TV app. interaction dialog (see also "CONFIGURE MENU", section "TV application interaction").

You can check if nxtvepg is able to interact with a specific TV application by starting both, and then opening the TV application interaction dialog in the Configure menu. The connection status is indicated in the middle of the dialog window. Only with cooperating TV apps, nxtvepg is able to automatically free the card when the TV app is started (TV viewing is always given priority over EPG data acquisition.)

After setting up the TV app type and path, unless you are using the Teletext EPG Grabber as source, you should open the Network name configuration dialog to synchronize network names between nxtvepg and the TV app. Even if interaction is not possible, it may still be a good idea to have the same network names in both applications. See "CONFIGURE MENU", section "Network names" for details.

BASIC BROWSING

The browser mainly consists of two windows: the upper one contains a list of programme titles, sorted by start time. All currently running programmes (or rather: all programmes that should be running according to their start time) are marked by a light blue background color. One line in the list is selected by a cursor; the lower window contains the attributes and description for this selected title. The amount of information available here depends entirely on the content provider.

The basic browsing of programme information works very straight-forward. You can either use the mouse or the keyboard cursor keys:

With the mouse, you can click on any title to select it and display its description in the lower window. Use the scrollbar to the left to scroll the listing forward to programmes further in the future, or the weekday scale on the right to jump to a specific time and date.

With the keyboard, use the Cursor up/down keys to select any title. For fast scrolling use the page up/down keys. With the Home key you always get back to the first title. With TAB and SHIFT-TAB you can move the keyboard input focus to other input elements, e.g. to the network and shortcut lists; to apply a selected theme or shortcut as filter press the Space key. The first 10 shortcuts can also be enabled directly from the main window with the digit keys 1-9 and 0. Control-C in the main window opens the context menu; Control-F opens the text search dialog; the Escape key is equivalent to the Reset button. The menus can be accessed by pressing the ALT key together with the underlined character in the respective menu button.

You can restrict the programme selection in many ways to make it easier to find what interests you. For example, you can restrict the list to programmes of a certain network; or you can restrict the list to movies only. This process is called filtering and explained in detail below, see "FILTERING". For the most common filter options there's a list of Shortcuts at the left of the main window. Note you can freely modify this list, see "FILTER SHORTCUTS".

Since version 2.5.0 nxtvepg offers two different layouts for the TV schedules: By default programmes of all channels are combined in a single list sorted by start time, i.e. one big table. Alternatively programmes can be separated so that each network has it's own column. This format is very similar to most paper-based TV magazines. In this layout you can scroll both vertically by start-time and horizontally by networks.

When you resize the main window vertically the difference in height will be added to the info text window at the bottom. You can adjust the proportions between program listbox and the info text with the "panning" button inbetween, i.e. by dragging the button you can resize the programme list.

nxtvepg can interact with TV applications (e.g. xawtv on UNIX; requires initial setup, see "GETTING STARTED") to provide a connection in both directions: Firstly you'll find a Tune-TV button in the main window below the clock. When you press it, the network of the currently selected programme will be tuned in the TV application. This also works with a double-click on the programme or pressing the Return key. By clicking the right mouse button above the Tune-TV button you can also pop up a small menu which offers basic TV controls. Secondly, when you change the channel in the TV application, the cursor in the nxtvepg main window will automatically jump onto the programme currently running on that network. You can manually trigger this reaction by pressing "i" on your keyboard. For more details see "CONFIGURE MENU", section "TV application interaction"

At the bottom of the window there is a status line which informs you about the state of the browser database and background acquisition. It's basically a very dense summary of the Statistics popups from the Control menu and is especially useful to warn you about the database age or stalled acquisition.

Note: For most content providers it holds true that programme content descriptions (i.e. the texts in the lower nxtvepg window) are available only for currently running programmes and those whose start time is very close. This time span for full coverage can be as short as 2 hours, or 3 titles per network. As a consequence you should enable data acquisition as often as possible; consider running the acquisition daemon permanently in the background. For details on the acquisition process see the following chapter.

TELETEXT EPG GRABBER

The Teletext EPG grabber allows extracting TV programme listings from teletext pages (broadcast by many European TV networks) and combining them into a single overview. The grabber works by reading teletext pages directly via a TV card from a list of configurable channels. From captured teletext pages it extracts firstly the programme overview tables and secondly description texts from pages referenced by overview pages. The extracted TV schedules can be loaded immediately into the display, but are also available as files in XMLTV format, so that any other XMLTV capable browser can be used to display the data.

Coverage provided by Teletext EPG obviously depends on the depth and quality of the listings each channel provides. Usually the minimum coverage is overview of programmes for the current and next day. Some channels provide full overviews for more than a week in advance. Most will provide additional pages with content descriptions at least for movies and popular series. Compared to other EPG sources, descriptions for news programmes and daily shows may be more precise and recent. On the other hand, one downside shared by all sources is a lack of categories (e.g. making it harder to search for movies).

For now, only nation-wide German networks are supported well. For other countries' networks the parser will need to be adapted to different page formats and languages. The reason is that almost every network formats tables, dates, times and descriptions slightly differently, so that the parser will have trouble locating the EPG data among all the advertisements and other content in teletext.

Since the grabber has to read each individual network's teletext stream and many networks use sub-pages at least for descriptions, the process unfortunately takes relatively long: For full EPG grabbing, typically between 90 and 120 seconds per channel are required. When receiving via DVB, this can be sped-up significantly however, as it's possible to receive teletext from all channels sharing a transponder concurrently. Still you should make sure to enable grabbing only for the channels you actually plan to watch to avoid wasting time.

EPG information in teletext usually isn't updated more than once per day (programme changes notwithstanding). Therefore it should be sufficient to run the grabber once per day. On the other hand, the grabber should be started at least every other day, firstly as some networks only transmit schedules for two days and secondly because even those which transmit longer overviews will omit description texts for programmes far in the future.

There are a few options that can be configured to change parameters of the grabbing process, such as the minimum duration spend receiving teletext for each channel, or the overview page range. Currently this is only configurable globally for all networks. See "CONFIGURE MENU" section "Teletext grabber" for details.

Using Teletext EPG

The Teletext EPG grabber stores the EPG data in files in XMLTV format, so in principle they can be loaded and viewed like any other XMLTV file via the "load" and "merge" commands (see chapter "CONTROL MENU"). To access the files, click on the little "down" arrow next to the Select directory entry field at the top of the dialog window and select "Teletext grabber XMLTV directory" from the drop-down menu. Then all the grabber's XMLTV files will be shown.

For the merge dialog, a more convenient way to include all of the grabber's files is keeping the button Automatically include Teletext EPG checked. This is equivalent to manually adding all of the grabber's files to the list on the right (except that any new files added by the grabber later, for example due to changes in the channel selection in grabber configuration) are included automatically.

However the most convenient way is using command Load Teletext EPG from the Control menu: It merges and loads XMLTV files created by the Teletext EPG grabber into the browser. The networks which are covered are determined by the channel selection in the Teletext grabber configuration. This mode is the default where there is no data and the Teletext grabber is enabled.

See chapter "CONTROL MENU" for more details on all of the mentioned commands and options.

For any of the above ways, programme display is updated immediately whenever the Teletext grabber has acquired new data. Every effort is taken to not alter the cursor position or title selection, except if the cursor is on the very first item - then the view and cursor are moved to the first item in the database, if a new one is inserted.

Acquisition modes

The basic mode of operation of the Teletext EPG grabber is to cyclically tune all TV channels in the configured channel table; For each one it tunes to the respective TV frequency and buffers teletext until the required page range was received completely. When done, it extracts EPG data from these pages and writes them to a file in XMLTV format. As mentioned above, for DVB this can be done concurrently for all channels sharing a physical transponder. You can follow the progress using the "Teletext grabber statistics" and "Database statistics" commands in the Control menu. See "STATISTICS" for details.

The teletext grabber configuration dialog allows selecting an acquisition strategy. The first two are for the special case that you do not receive TV via the internal tuner, so that nxtvepg cannot switch channels. The others are for controlling the timing for searching EPG on multiple channels.

Cyclic: Full

This default mode works straight-forward as described above. This means, each channel in the channel table is tune for as long as it takes to load all required sub-pages and then the full EPG is extracted and written. Acquisition is complete after a single cycle across all channels.

Technical details: Since transmission errors have to be considered, it's actually not attempted to load every single sub-page of the given teletext range before acquisitions switches to the next. The grabber will just wait for as many page cycles as the highest sub-page count in the given page range. (Note most teletext providers will not use sub-pages for today's schedules, but may use a single page with many sub-pages for following days. Only a single sub-page per page is transmitted per cycle; the length of a cycle depends on the overall number of pages; a typical cycle time is 20 seconds.)

Cyclic: Now - Full

In this mode channels are not just grabbed from completely one after another. Instead, a 2-staged round-robin is implemented. In the first stage, only a single cycle of the EPG teletext page range is loaded. This is enough for capturing today's schedules, as these are usually listed on separate pages that do not involve sub-pages. Only after this has been completed for all TV channels, the second stage begins, which loads the full EPG in the way described above.

During the "Now" phase the grabber uses an optimized strategy during the "Now" stage in which waiting times are minimized by changing the order in which EPG data is read. This way the grabber requires about 15-20 seconds per channel in average. The strategy does not work well for DVB due to concurrent reception from multiple channels; the phase is still quicker for DVB, but mainly due to a reduced capture duration of only 30 seconds per channel.

Passive

In this mode the software never accesses the video device and never changes the input channel or tuner frequency. It's useful if you want to set up the source with command line tools like v4lctl. If you're using applications which keep the video device busy (e.g. a TV application) you don't need this mode, because when nxtvepg detects an unsolicited channel change, it automatically switches to the passive mode for as long as the video device remains busy.

Please note: when nxtvepg does not control the input channel, it can not automatically take care of updating your databases. Even if the browser database should be completely empty, no data will appear until you tune in the content provider's channel manually with an external application. Because of this, passive mode is depreciated.

Which mode is best for you depends on how you use the browser. When you are mostly interested in today's schedules, use the "Now - Full" mode. If you want the full schedules, it's quicker to use "Full" right away. (Note that the time until all databases are complete is longer in the "Now - Full" mode than in "Full" mode. In general, the time used for the Now stage just adds to the time to complete full acquisition.)

STATISTICS

There are multiple ways to obtain information about the state of the databases and the acquisition process: the first and most obvious is the status line at the bottom of the main window (only if enabled, see "CONFIGURE MENU"). The second one is the timescale popup window, which visualizes for each TV network the time ranges which are covered with TV programme data. The third one is the database statistics popup window which offer technical details about the database (e.g. how many programmes are available per day etc.), both in textual form and as charts. Finally, there's a status window for the Teletext EPG grabbing process showing the overall state of acquisition and statistics about teletext packets received from TV networks.

Status line

The status line separately summarizes the state of the browser database and the acquisition process. Since there is not much room, only the most relevant information is included there, i.e. the kind of information presented depends on the current state.

For the browser database you'll normally just see the name of the XMLTV file. If the database is more than a day old, its age and the percentage of programme information that expired since the last update is appended. (Note the frequency of required updates depends on length of coverage and dynamics of your EPG provider; for the teletext grabber it's recommended to update data at least once a day, see "TELETEXT EPG GRABBER".)

If the Teletext EPG grabber is enabled, acquisition status is indicated following the database status. The status indicates if acquisition is currently enabled, and if so, to which percentage it is done and which channel is currently received from. Additionally, there may be a note about the current phase of acquisition, indicating "Now" when quick initial refresh is ongoing (if enabled in Teletext grabber configuration), of "Full" while the full range of TV schedules are captured, or "Complete".

In case there is no reception or other kinds of errors, this is also indicated here. In particular, the note "forced passive" means that nxtvepg is not able to tune the TV channels it would need to update the database, most likely because some other application is already using the TV tuner. (See "TELETEXT EPG GRABBER" for details.)

Timescale popup window

You can get a quick overview of EPG coverage for the different networks using the timescale window which can be opened from the Control menu.

The timescale window has one scale for each network covered by the XMLTV input file (or merged files). The left end of each scale refers to the start time of the oldest TV programme in the database. Depending on how long ago the database was updated, and on how long expired programmes are kept by your EPG provider, some or all TV programmes may lie in the past. The exact dates are printed in the date scale at the top of the window, the current time is additionally marked with a small arrow labeled "now".

Ranges that are covered by the database are marked in shades of yellow, red and blue. Uncovered ranges in-between are marked gray. The ranges before the first and beyond the last programmme of each network is left black. The detailed meaning of colors is as follows:

bright red:

Programme data covering today's TV schedule. Note with respect to this color mark-up, a day starts at 6 o'clock in the morning.

pink:

Programme data covering tomorrow's TV schedule.

blue:

Programme data covering TV schedule after tomorrow.

dark red, pink, and blue:

Same as above, however the programme data was acquired more than a day ago.

dark yellow / orange:

Expired programme information (i.e. stop time is in the past)

yellow:

Invalid programme blocks (i.e. zero or negative run-time, or overlapping with other programmes in the schedule)

gray:

Gaps between programme coverage, possibly due to gaps in TV transmission, for TV channels that do not broadcast full 24 hours per day, or due to lost data in EPG acquisition (e.g. due to decoding errors in Teletext).

black:

Time range which is not covered by the content provider.

Programmes for which description texts are currently available are additionally marked by an increased height of the scale in the covered time range.

Database statistics

The database statistics popup window is opened via the Control menu. It displays statistical information about the EPG database loaded in the main window.

Last update:

The time when the database was updated (according to its file modification timestamp). For a merged database this is the latest time when any of the merged files was updated.

Networks in db:

The number of TV networks covered by the database.

Blocks in db:

How many blocks are in the database.

Blocks today/...:

How many blocks are in the database covering the TV schedule of today, tomorrow, and the days after tomorrow, respectively. Note expired blocks are not counted, therefore the first value is usually lower.

Expired total:

Total number and percentage of expired blocks in the database (i.e. programmes whose stop time is in the past). Note it is normal for this value to increase over time, until the next database update.

During updates, it depends on your data provider and grabber if expired programmes are removed immediately, or kept for some time (e.g. to allow looking up description of programmes after they ended, as you can do via the Expired display filter.) For the Teletext EPG grabber, you can configure this threshold (see "CONFIGURE MENU" section "Teletext grabber").

Expired since acq.:

Total number and percentage of blocks in the database that expired since the database was updated (where the time of update is determined by the timestamp of the respective XMLTV source file). This value is equal to the "expired total" when your provider or grabber remove all expired programmes during updates.

Defective blocks:

Number of blocks with invalid blocks in the database (i.e. zero or negative run-time, or overlapping with other programmes in the schedule). These blocks do not show up in the browser (as it would be impossible to handle if there is more than one "now" entry for a network).

The pie chart on the left on the window visualizes these numbers. The circle represents 100% of the blocks in the database. It's divided in four parts: yellow for expired and defective programmes; red for today's programmes; pink for tomorrow's programmes, and blue for the rest. For each of the latter three, the portion of programmes whose data was acquired before the current day is marked stippled.

While Teletext EPG acquisition is enabled, the histogram below the pie chart shows the same information as the pie chart, however tracked over time. The state information printed to the right of the histogram has the same meaning as described in the next chapter for Teletext grabber statistics.

Teletext grabber statistics

The Teletext EPG grabber statistics popup window is opened via the Control menu. The window contains two separate parts: The upper part shows configuration and overall state of acquisition. The lower part shows a table that indicates a number of statistics about teletext reception for all currently received TV channels.

Description of information in the upper part of the window:

Acq mode:

The current acquisition mode as configured by the user, and the mode's currently worked-on phase: "Now", "Full", or "Complete".

Acq passive:

When acquisition is not allowed to or not able to tune TV-channels, this line states the reason. It could be that the acquisition mode is configured to passive, or that tuning of TV channels failed.

Channels done:

Indicates the number of TV channels that are configured for Teletext EPG acquisition, and how many of these are already received.

Current channels:

The number of TV channels where Teletext is currently captured from. For analog input devices this is always zero or one, but DVB allows capturing concurrently from multiple TV networks (i.e. all networks sharing a physical transponder.)

Acq. runtime:

How long the acquisition has been working on the current channel, in seconds (i.e. format MM::SS). The value in parenthesis states the capture duration configured for this channel in the Teletext Grabber configuration.

Acq. state:

State of Teletext reception on the currently tuned channel: "Capturing" means Teletext pages are being received from the configured page range; "starting up" means the grabber is waiting for the first of the configured pages to be received; "scanning" is printed during phase "Now" when checking the stream of different TV channels for the one where the first configured page can be received with smallest delay.

The lower part of the window shows a table: The first row shows the names of the TV channels which are currently received. The following rows show statistical information for each of the channel in the respective columns.

Channel VPS/PDC:

The VPS/PDC channel identification code that has last been received on the respective TV channel. Source may be PDC (packet 8/30/2), NI (packet 8/30/1), or VPS. The given CNI is the equivalent PDC code, if defined, or else the NI code.

If a valid VPS PIL (Programme Identification Label) was received, this is appended in decoded format (i.e. DD.MM HH:MM with day, month, hour and minute). Note this label indicates the original starting time of the programme that is currently broadcast by the network. This was traditionally used by video recorders to start and stop recording exactly at start and stop of a programme, even when not matching the TV schedule.

Capture range:

This is actually the configuration value entered in the Teletext Grabber configuration. It specifies the first and last teletext page number which are captured for grabbing EPG for each TV channel.

Captured pages:

Number of Teletext pages received from the given capture page range (including repetitions and sub-pages, i.e. this is simply the number of received page headers).

Captured packages:

Number of processed Teletext packets from the given capture page range. Note a teletext page usually consists of 23-25 packets, although blank lines may be omitted. The second number of this table row indicates the percentage of processed packages compared to the entire Teletext data stream.

Decoding errors:

Indicates the number of Teletext characters for which decoding errors were detected (control information is Hamming-8/4 protected, text data only parity protected). The percentage is calculated relative to the total number of received Teletext packages with 45 bytes each.

TTX data rate:

The rate at which teletext data lines are received on the current channel in baud, i.e. bits per second. Each teletext line counts as 45 bytes.

MERGED DATABASES

The primary use for merged database is when you have different EPG providers that cover different sub-sets of networks you can receive. In this case the merged database allows bringing together the EPG data for all networks in the browser.

The second use for merged databases is when you have multiple EPG providers that cover the same network. In this case merging accumulates the data from both providers for display. For information elements such as descriptions, text from all providers is concatenated. For attributes that cannot be accumulated, the attribute from the first providers that supports it is selected (see details below).

When you select the Merge XMLTV files entry from the Control menu, you will get a dialog with two listboxes: the left one contains a list of XMLTV files in the directory selected at the top of the dialog window. Click the button next to the entry field to open a directory selector dialog. You can also edit the directory name directly and press the Return key to update the list of files. By default, only files with extension ".xml" are shown; You can remove this filter by selecting "all (*.*)" from the drop down menu below the directory name.

The list on the right side of the dialog shows XMLTV files selected for merge. Initially the list will be empty; After having merged databases once, the right side will show the previously used configuration, if the used files still exist. You can add files to the list on the right by selecting an entry in the list on the left side and pressing "Add". Inversely, you can remove entries from the list on the right side by selecting them and pressing "Delete". Entries can be reordered in the list on the right side by selecting one or more entries and pressing the arrow buttons in the middle between the two boxes. When you're done with your selection, press Ok to start the merge and switch the browser to the newly merged database.

By ordering providers in your selection, you assign priorities which are important for conflict resolution. A conflict occurs when programme start and stop times differ between providers. The likelihood of such conflicts depends on the quality of your providers; theoretically they should never happen except if there are late program changes. In reality, conflicts are not that unlikely, particularly for programmes early in the morning. You should put the most reliable provider in the first position, because conflicting programmes from providers further down will be rejected, i.e. not added to the merged database.

When enabling option Automatically include Teletext EPG, all XMLTV files created by the Teletext EPG grabber are automatically included. Even new files created by the Teletext EPG grabber after initiating the merge will be added automatically. The order of files is undefined when using this option, but this is normally not an issue as each file contains only one network, so that there will be no conflicts in-between Teletext EPG. If you want to add the files manually, switch the XMLTV list on the left to show the grabber's cache directory by selecting Teletext grabber XMLTV directory fro the drop-down menu that opens when clicking the little down arrow next to the directory entry field. After that select all files in the left list and add them to the list on the right by clicking the "add" button.

The Configure button in the dialog gives you fine-control over the priority of providers during the merge of all distinct programme attributes. You can even completely remove a provider as source for an attribute (e.g. if they transmit false data). An exception is the title, where you must not delete any providers.

Attributes that cannot be merged, e.g. editorial rating, are fetched from the first database in the list that contains the attribute for a given programme (see also "FILTERING").

FILTERING

The commands in this menu allow controlling which of the programmes in the database are presented in the listing. There's a filter for every kind of attribute that can be attached to a program, for example its network, start time, theme categories, or description text.

Filters can be undone either singularly by selecting the same filter menu entry again, or globally by clicking on the Reset button.

You can combine as many filters as you want to build a complex filter. If you combine two filters of different types, only programmes that match both attributes will be listed (logical AND). If you choose more than one filter of the same type, all programmes that match either attribute will be listed (logical OR). Note some filter types also support multiple "classes" which allow logical AND within a category; this is explained in more detail in the filter types list below.

Examples: If you want to get all programmes listed for either network A OR B, simply select both networks in the filter list. If you want to see all movies scheduled on A, i.e. all programmes which run on network A AND are flagged as movies, select network A and from the themes dialog all categories related to movies.

Filter Types

The following filter types are available:

Theme categories

Restrict the listing to programmes that have any a given theme categories attached to them. When selecting more than one category, programmes that jave any of the selected categories are shown (logical OR).

The list of available theme categories is built from categories attached to programmes in the database. Therefore the list of categories will change between EPG providers. Unfortunately this means that shortcuts with theme filters may not work across different providers. (For this reason there is no theme shortcut in the default shortcut list.)

For providers using hierarchical theme categories, multiple themes may be associated with individual programmes. For example, there may be main categories "Movie" and "Series" and sub-categories "Comedy" et.al. In that case, selecting theme categories "Movie" and "Comedy" would also show comedy series. To show only comedy movies, one needs to apply a logical "AND" between the categories. This is done by selecting the two categories in different "theme classes". For example, first select "Movie", then select class "2" via the selection box at the bottom of the theme selection dialog, then select "Comedy". The actual used class numbers do not matter, you just need to use two different ones. There will be logical "AND" between themes in different classes.

Networks

Restrict the listing to programmes of one or more given networks. The filter is disabled when all checkbuttons are deactivated.

You can also add a network filter listbox to the main window by enabling one of the Show networks checkbuttons in the Show/Hide sub-menu of the Configuration menu (see "CONFIGURE MENU", section "Show/Hide"). Also note that selection, order and names of networks are all configurable, in particular you can permanently suppress uninteresting networks from the list.

Text search

Restrict the listing to programmes who's title or description (or either if both options are enabled) contain one of the given character sequences. If you enable the match complete text option, an exact match will be required, i.e. a search for "heute" will not match on "heute journal" (intended for title-only searches, as started from the context menu). If you enable option match case, character case is relevant, i.e. a search for "heute" will not match on "Heute Abend".

You can search for more than one text at the same time; you'll get all programmes that contain any of the given texts (logical OR). The listbox above the text entry field lists all currently active texts. You can double click on the options in the list to toggle them between "yes" and "no" (i.e. option enabled or disabled). The entries also have small context menus which allow to remove single texts or toggle options.

Press Click here to open... to open a small dialog which allows to swiftly add a large list of texts (e.g. a list of your favorite movie titles.) You can paste text for example from a text editor into the dialog or load them directly from a file. Each line in the text fields will be added as a separate search when you press OK and all new entries will have the same options. Blanks at the beginning or end of lines are automatically removed and lines starting with # are skipped when loading from a file.

A history of the last 50 searches (manually entered ones only) including options, are stored and available in the drop-down menu below the search text entry field (opened with the arrow button at the left or one of the up/down cursor keys) and the last 10 searches are also available in the Title column header menu in the programme list (the latter in "single list" layout only).

Recurring titles

The filter menu of this name lists all programme titles that occur more than once in the database. Internally the option is mapped to a text search. Therefore if you want to remove one of the filters set this way, use the Text search dialog.

Features

Restrict the listing to programmes that match all given attributes (logical AND), i.e. sound format, picture format, analog/digital, encrypted yes/no, live/new/repeat and subtitles yes/no.

If you want to allow more than one value of the same attribute (e.g. picture format wide OR Pal+) you have to put them into different feature classes (e.g. first select format wide, then set filter class to 2, then select format PAL+)

Parental Rating

Restrict the listing to programmes that are suitable for children of the given age or elder, e.g. when you select 14, you get all programmes that are recommended for children of age 0 to 14.

Note you can use inverse searches (see below) to find programmes which are recommended only for children above a certain age. For example, if you invert a parental search with age 14, you'll get all programmes that are recommended for children of age 16 or older.

Editorial Rating

Restrict the listing to programmes that are rated (by the content provider) to have at least the given quality. The range of rating values is 1 to 7.

Note that some providers do not use all values, e.g. only 1, 3, 5 (thumb down, middle, thumb up.) For that reason only the first provider's ratings are used when merging databases (see also "MERGED DATABASES")

Start time

Restrict the listing to programmes whose start time lies in the interval and whose start falls onto the given date or weekday.

Following options are available: If you enable Start at current time the interval start is fixed to the actual time when the filter is set and the value given as stop time is interpreted as duration, i.e. it's added to the interval start. If you enable Stop at end of day the interval end is fixed to 23:59 of the same day.

For the date you can chose between the following modes: Ignore date: the filter allows programmes that start on any day (in the time window given above). Relative date: allow only programmes that start N days from today, i.e. for zero: today, for 1: tomorrow etc. Weekday: allow programmes starting at the given day of the week (the scale runs from Saturday until Friday.) Day of month: allow only programmes starting the Nth day of any month (the scale runs from 1 to 31.)

Note that the main intention of this filter is to support time restrictions in the provider's navigation menus (see "NAVIGATE") or shortcuts. For manual navigation there are more practical alternatives, e.g. the weekday scale and drop-down menus in the main browser window above the time and date columns (not available in grid layout.)

Program index

Restrict the listing to programmes who's index is in the given range. The currently running programme of each network is given index zero, the following programme of each network index one etc. The three most important combinations are available as radio buttons: now (range 0-0), next (range 1-1) and now or next (range 0-1).

For merged databases only indices 0 and 1 are supported.

Duration

Restrict the listing to programmes whose duration (i.e. difference between start and stop time) lies in the given range. When the maximum is set to zero, the filter is switched off.

You can specify the time values either by use of the scales or by entering a value in the format MM:HH into the text fields and pressing the Return key.

Expired Programmes Display

Unlike all other filter options this one is used to enlarge the set of matching programmes. By default the threshold is zero so that expired programmes immediately disappear from the list. The options in this dialog allow including programmes with a stop time in the past into the list; They will be marked with a yellow background (you can change that color, see .Xdefaults and nxtvepg.ad in "FILES".)

With the slider you can select how for to shift the expire time threshold into the past. The entry fields below the slider show the threshold in units of days and hours. You can also edit these fields directly: Press the Return key to apply the change.

When enabling check-button "Show all expired", then filtering of expired programmes is disabled. The list will then start with the oldest programme that is still present in the database.

Note you cannot add more programmes this way than are stored in the database. nxtvepg will not remove expired programmes from the database, however they usually get removed whenever you update the respective XMLTV source file. If and how long expired programmes are kept, depends on your provider. For the Teletext EPG grabber, you can configure this threshold (see "CONFIGURE MENU" section "Teletext grabber").

VPS/PDC

Restrict the listing to programmes that have a valid VPS/PDC start time label attached (VPS/PDC allow to start a video recording at the exact time a programme starts even when delayed; VPS/PDC labels are in use in Germany, Austria, Switzerland and England). Additionally you can filter for programmes with a label which differs from the actual start time; these are usually programmes whose start time changed or which were scheduled later (usually the VPS/PDC label then is the actual start time minus one minute)

Inverting filters

Near the end of the filter menu there's the Invert sub-menu which allows to invert the outcome of filtering. There are two levels of inversion: global and individual.

When you select global inversion, you'll get exactly the programmes that otherwise would have been filtered out (except for programmes which are permanently filtered out by your network and air-time selection). In other words, all programmes which match your current filter setting are removed from the list. Note: due to the way filter shortcuts are merged when more than one is selected at the same time, it's in most cases not recommended to use global invert for filter shortcuts unless you change the combination rule (see "FILTER SHORTCUTS: Shortcut combination modes".)

The invert menu also allows to individually negate certain filter types (there are also invert buttons in some filter sub-menus which have the same function). The logic of combining filters is the same as without inverting, i.e. there's a logical OR between filters of the same type (e.g. network A OR network B) and a logical AND between different filter types (e.g. network A AND theme category movie).

Example 1: If you want all programmes which are neither categorized as sports nor as children's programmes, select theme filters sport and children's and then invert the current theme filter (usually class #1; you can equivalently use the global invert if themes are the only filter).

For the theme filter it's possible to invert only parts of the selection, so that you can require that a programme has a certain attribute and at the same time require that it doesn't have another attribute.

Example 2: If you want all programmes which are movies but NOT adult movies, select theme category Movie, switch the theme class to 2, select theme adult and then invert theme class 2.

Note: although the Feature filter offers the use of different classes so support a logical OR, the inversion is not based on classes. This is due to the fact that there's a logical OR between feature classes (in contrast to the logical AND between theme classes).

FILTER SHORTCUTS

There's a number of predefined filter options in the main window below the clock. These shortcuts enable you to invoke filters by a single click of the mouse. You can freely add, change or remove entries in this list.

When you want to add a shortcut, first set the filters up in the way you want to save them, i.e. either choose existing shortcuts or select an entry from the filters via the main menu or context menus. When you have found an interesting selection, invoke Add filter shortcut from the shortcuts menu.

This will open the shortcut edit dialog (which will be described in detail below) with your new shortcut at the start of the list at the left. You should change the shortcut label in the field at the top right; by default it's just "new shortcut". The label will be displayed in the shortcut list in the main window. When you're done press Save, or Abort if you've changed your mind and don't want to add this shortcut after all. If you want to define multiple shortcuts you can leave the Edit dialog open and save just once when you're done with all changes.

You can invoke several shortcuts in parallel by moving the mouse with the left button pressed or by pressing the CTRL or SHIFT keys when selecting in the main window's shortcut listbox. See the chapter below for possible side-effects when combining shortcuts.

The shortcut list has a small context menu which shows when you click with the right mouse button into the shortcut list. If offers faster access to the same commands which are available in the main menu plus a Delete command; the shortcut above which you press the mouse button is pre-selected for the chosen operation.

When you Update a shortcut and your current filter setting contains different filters than the previously stored setting, you'll be asked if the filter mask should be automatically adapted (e.g. if your filter previously searched for theme category 'movie' but your current filter consists of a text search). See below for more details on filter masks; unless you have manually edited this shortcut's mask before, you can safely press "Yes".

Editing Filter Shortcuts

To change names and/or organization of your shortcuts, open the edit dialog (e.g. via the main menu.) On the left of the dialog window there's a list of all your shortcuts. In the middle there's a row of command buttons which operate on the shortcut selected at the left (explained below). At the right there's an editable field with shortcut name, a read-only display of the filter settings currently assigned to the shortcut, and popup menus to change the filter's mask and combination rules (also explained in detail below.)

The buttons with up/down arrows will move the selected shortcut up or down. The buttons with arrows pointing to the upper left and lower right are used to move a shortcut entry out of or into a sub-folder respectively.

The Delete button removes the selected shortcut from the list (the deletion won't affect the main window until you press Save, so you can leave the dialog with Abort to undo the operation.)

The Invoke button will apply the shortcut's filter setting to the main window just as selecting the shortcut in the main window's list. You can then change the filter settings via the filter menus. Use the Update button to assign the main window's filter settings to the edited shortcut.

You should be careful with the update button since it's easy to overwrite the wrong shortcut. If you notice such a mistake, you can undo the change either by leaving the edit dialog with the Abort button or selecting the respecting shortcut in the main window and assigning the original settings via Update.

Filter Masks

When you deselect a shortcut, either by selecting another shortcut or clicking on it a second time with CTRL held down, all it's filters will automatically be undone. Hence when you have two themes shortcuts, e.g. "Movies" and "Sports", and select first Movies, then Sports, you'll see only sports programmes afterwards. However if you had selected theme movies manually, e.g. by the context menu explained in the next chapter, the movies filter might remain set, so that you'd get all programmes of theme movies OR sports. Since that is usually not what one expects, a filter mask has been introduced to the shortcut setting.

The filter mask is defined in the shortcuts dialog with a checkbutton for each filter category. By default, the mask is enabled for every filter category you've included in the shortcut filter setting. When you invoke the shortcut from the main window later, all filters of the given categories will be cleared (masked out) before the shortcut filters are added. To return to the above example: if the "Sports" shortcut is defined with a themes mask, the manually set movies filter would be cleared before the theme filter is set to sports.

The masking can also be enabled when no filter of that category has been chosen. This can be used to define undo shortcuts. E.g. choose the mask 'Themes' if you want a shortcut that allows to clear all theme-related filters at once. Or enabled all masks for a Reset button (the only difference to the pre-defined Reset button would be that the cursor does not jump to the first Now programme.)

Shortcut combination modes

By default when combining multiple shortcuts, all filters of all selected shortcuts are simply thrown together (i.e. "merged") and then processed as if they belonged all to one shortcut. The same combination rules apply as described in "FILTERING".

For example, if one shortcut searches for movies, another one subtitles, the combination will search for programmes which are movies AND have subtitles, as this is the default when combining filters of different types. Inversely, if you have one shortcut which filters for category "Drama" and one that filters for category "Comedy", the combination will filter for all programmes which are either in category "Drama" OR "Comedy", as this is the default when combining filters of the same type.

For such simple shortcuts which consist of a single filter type this behavior is usually intuitive. When combining complex filters the result of merging however might not match your expectations. For example, if you have a shortcut "Drama on network A" and one "Comedy on network B", merging would result in "either Drama or Comedy, on either network A or B", i.e. the list would also include Comedy on network A and Drama on network B.

Hence the shortcut edit dialog has a Combination rule option where you can change the mode into OR or AND. If you put a shortcut into this mode, it's filters will be handled separately from all others.

The only drawback is that the shortcut's filters will not be editable via the filter menus. If you ever want to change the filter settings without creating them from scratch, use the Invoke and Update buttons in the edit dialog (see "FILTER SHORTCUTS: Editing Filter Shortcuts".)

Shortcut update dialog

When you select the Shortcut Update command in the main menu, there will be a small dialog with a list of all shortcuts. The filter settings of the shortcut you select in this list will be overwritten with the currently active filter setting once you press the Update button. You can also use the Update & Edit button to jump directly into the filter edit dialog (see further above in this chapter)

Note that while the shortcut edit dialog window is open, updates (as well as deletions or additions) will only affect the temporary list in the edit dialog window until you press the it's Save button. Also the list offered for shortcut updates consists of the shortcuts as they are defined in the temporary list. This allows to test your changes before you commit them.

Note that a faster way to change a single shortcut is to use the context menu, since it allows to skip this intermediate dialog.

COMPOSITE ATTRIBUTES

By default the TV schedule contains for each programme "basic" attributes like its date, starting time, title, TV network in a pre-defined textual format. By using composite attributes you can customize the TV schedule according to your personal preferences. For example you could (1) alter the display format of pre-defined attributes (e.g. use colors for highlighting), (2) add new attributes, for example with images as markers for favorite programmes and/or (3) compact display by combining several attributes into one.

Composite attributes replace single attributes in the display (e.g. only the theme category column.) Newly created composite attributes will be appended to the list of pre-defined attributes. You can then configure your programme list as a mixture of pre-defined and composite attributes (see "CONFIGURE MENU", section "Select attributes")

Composite attributes are created and edited via the Attribute composition dialog in the Configure menu (see "CONFIGURE MENU", section "Attribute composition")

The "heart" of attribute composition is a list of filter shortcuts and reminder groups, which you build as a subset of your personal filter shortcuts and/or reminder groups (see also "FILTER SHORTCUTS" and "REMINDERS".)

Whenever nxtvepg displays a composite attribute in the browser, it matches the programme's actual attributes (e.g. theme categories or assigned reminders) against the shortcuts and reminder groups associated which the respective composite attribute, in the given order (top to bottom in the dialog's list - so order is important). If a match is found, the text, image or attribute which was assigned to that specific shortcut match is displayed in the column with the format specified for this match. If none match (and there's no *no match* entry, see below), nothing is displayed in place of the composite attribute.

Note in this context matching means that a shortcut's filters are tried against the TV programme, i.e. a programme "matches" a filter when it would remain displayed when you enable that filter shortcut in the main window. A reminder group is considered matching when the respective TV show is programmed as a reminder in that group (or matches a shortcut which is assigned to the given reminder group - but let's ignore that for now to avoid confusion.)

Example: to create a personalized version of the Editorial rating (ER) column, you could create three shortcuts: one with the ER filter set to ">=6", one with ">=4" and one with ">=2"; then you'd create a new user-defined column and insert the three shortcuts in this order; to the first shortcut match you'd assign the text "great", to the second "ok" and to the third "bad". As a result you'd have a column where the numerical ratings are replaced with your texts.

There is also a special entry at the end of the dialog's shortcut list called *no match*. It acts as a catch-all (i.e. wildcard) if none of the shortcuts in the column matches the current programme entry. In the above example this would be all programmes with an ER below 2 or without a rating.

The catch-all is particularly useful to overlay standard columns with alternate texts for selected programmes. To stay with the ER example, you could define a column with two shortcut entries: ">=6" and "*no-match*". To the ">=6" shortcut match you could assign an image marker; to all other the "ER" attribute. Hence programmes with an ER >=6 (i.e. all "great" programmes) would have an image displayed and hence clearly stand out from all other programmes, which get the regular content of the ER column (i.e. the numerical rating or an empty column for unrated programmes).

You can also use this mechanism to combine several columns into one, to keep the listing compact. For example you can combine the ER column with the theme column, so that for movies with ER >= 6 the text "great movie" is displayed, for all others the regular theme description.

REMINDERS

Reminders allow to mark TV shows which interest you and have nxtvepg mark them in the programme list and optionally display a message or execute an external command before they start. You can select either individual programmes in the programme list or complete filter shortcuts, e.g. for TV series.

To set a new reminder, simply select it with the cursor in the programme list and choose Add reminder for selected title from the Reminder menu. The same command is also available in the context menu, i.e. by clicking on the selected title with the right mouse button. To remove the reminder, open the context menu again and choose Remove reminder for selected title.

By default nxtvepg will display a message popup for every reminded programmme 5 minutes before and once more directly at the start time. You can change this in the Configure reminder groups... dialog described in a separate chapter below.

If you want to set a reminder for an entire series, you need to create a filter shortcut first which matches the series (e.g. filtering by title). To reduce the overhead, you can create a shortcut which matches all your favorite series and set a reminder for this collection. To assign a reminder to the shortcut use the Edit reminder list described in the next chapter.

Note you can add a single reminder for entries which already match a shortcut reminders. This allows to assign an additional, specific action for that TV show (if you use different groups.) Additionally, you can suppress handling of reminders for individual shows; this option is offered in the Reminder and context menus when applicable. (This possibility may help avoiding the need for excessively complex or restrictive shortcut filters.)

By default, nxtvepg has (in the single list layout) a column titled Mark which contains a red dot for all programmes which have a reminder registered, i.e. both single programmes and those which match shortcuts with associated reminders. You can also set a filter which will display only programmes with reminders in the programme list by selecting Show reminder matches from the Reminder menu.

Edit reminder list

Opens a list of all reminders. Single programmes and shortcuts are listed in separate "tabs"; switch between them by clicking on the buttons at the top.

The single programmes list is sorted by start time and network. When you double-click on a reminder, the respective network will be filtered for in the programme list and the cursor jumps onto the programme (if it's present in the current database.) To delete a reminder click on the Delete button or press the delete key on your keyboard. You can also select the reminder's "group" (see below) either by selecting a group in the popup menu from the Set group menubutton or by clicking with the right mouse button into the group column.

The list will normally not contain reminders for programmes which are already expired. You can use the Display popup menu at the right to change that. You can also include "suppressed" reminders, i.e. entries which where created via the respective entry in the main menu to supress shortcut matches; those will appear with the virtual suppress group in the list.

When you switch to the Shortcuts tab, you'll see a list of all shortcuts for which you have added reminders. The first time you open the dialog it will be empty. You can add shortcuts by selecting them from the popup menu at the right. Equivalently to single programmes you can change the group or delete the reminders again. All changes to the lists are immediately saved and the markers in the programme list updated.

All changes you make in this dialog take effect immediately.

Reminder group configuration

Opens a configuration dialog for reminder groups. Every reminder is assigned to exactly one group which determines which actions are executed at the programmes' start time. Having groups allows to change actions (and especially: disable them if you're not in the mood to watch TV) easily without having to edit every single reminder. When you create a new reminder with the simple "add reminder" menu command it will be assigned to group zero.

By default nxtvepg has only one group which pops up a message 5 minutes before and directly at the start time. You can change this by selecting the group in the list at the left and then modifying the parameters at the right. Or create a new reminder by clicking New. You can also change ordering of groups (only available for your convenience; except for group zero ordering is not relevant.) The Show buttons sets a filter for the programme list so that only programmes matching reminders in the same group as the currently selected shortcut are displayed.

At the top of the parameter input section is the Label entry field. It allows to give the group a name, which is then used in the reminder lists and in reminder confirmation messages. Below is a checkbutton called Temporarily disable all group events. While enabled all actions for that group are suppressed, i.e. you'll get no popup messages and scripts are not executed. Note this setting only applies to the current session and is reset when nxtvepg is restarted (you should clear the action lists if you want to disable reminder messages permanently.) The programmes are still marked in the listbox though.

Further below is an entry field where you can give a list of comma separated values which define at which offsets reminder messages are displayed; offsets are subtracted from the start time, i.e. when you enter "5" a message will appear 5 minutes before the programme's nominal start time. You can use negative values (e.g. "-5") if you want reminders to appear later than the start time. In addition you can set start times for commands. Commands are silently executed in the background, unless you enable Ask before executing script.

Note configuration changes (including group additions or deletions) are not applied before you leave the dialog with OK.

Reminder Messages

Once the nominal start time of a "reminded" programme (minus the configured time offset) is reached, a message window will appear. If there's more than one message triggered at the same time, or if you leave the window open and reminders for additional programmes are triggered, they will all be collected in this window; in this case there's a cursor which determines to which reminders the controls explained below apply. When you press Ok all messages are marked as "done" and will not appear again. With a double-click or the Tune-TV button you can switch the channel of a connected TV application to the selected programme, just as in the main programme list.

For message windows there's several buttons which allow to control further reminder processing. Suppress will prevent any subsequent messages for the programme. (Note that this is not the same as suppressing reminders in the main menu, since here you suppress only messages but the programme remains marked as reminder). Repeat allows to schedule additional reminder messages at arbitrary time offsets. Note that messages configured for the group are suppressed until the manual repetition but will re-appear afterwards.

CONTEXT MENU

A quick way to select and deselect filters is by using the context menu, which opens when clicking with the right mouse button onto a programme entry in the main browser window.

This menu consists of several parts, separated by horizontal lines, which depend on the currently selected programme and hence are not always present.

Undo currently selected filters

The first section holds entries which allow disable currently selected filters either one by one or globally (reset). See also "FILTERING: Filter Types"

Add new filters

The second section offers a number of possible new filter options, which depend on the currently selected title and the already selected filters. The offered filter types include: themes and network of the selected programme title, repeat or original transmission suppression (only in conjunction with title text filters) and last but not least the title text.

The title text filter allows to check very quickly for repeats of a programme. These filter options are included only if there is another programme with the same title.

Add reminder

This menu entry will add a reminder for the currently selected programme. The reminder will have the default reminder group. To create reminders in different groups use Add reminder into group in the reminder main menu (see also "REMINDERS")

User-defined entries

The optional fourth section is empty by default, but can be used to invoke user-defined external commands on the selected programme. More precisely, you can execute any command with properties of the selected programme (like title or start time) on its command line. The user commands can be added via the Configure menu (see "CONFIGURE MENU", section "Context menu configuration").

CONTROL MENU

Summary of commands available from the Control menu:

Load XMLTV file

Open the XMLTV file selection dialog. This dialog lists all XMLTV files in the directory selected at the top in the list at the left. Click the folder button next to the entry field to open a directory selector dialog. You can also edit the directory name directly and press the Return key to update the list of files. (Note only files that have extension ".xml" and contain valid XMLTV schema are shown in the list.)

When clicking once on the name of a file in the list at the left, the provider name stated in the XML file and the list of covered channels are shown in the info boxes on the right side of the dialog. When double-clicking on a file name, or when cleaving the dialog via the "Ok" button, the selected XMLTV file will be loaded into the browser.

If the file hasn't been updated for a long time, the programme list might be empty (i.e. all programmes expired). In that case restart the grabber you used to create the file.

Merge XMLTV files

Open a dialog that allows to merge several databases into one. See "MERGED DATABASES" for details.

Load Teletext EPG

Merges and loads XMLTV files created by the Teletext EPG grabber into the browser. The networks which are covered are determined by the channel selection in the Teletext grabber configuration. This mode is the default where there is no data and the Teletext grabber is enabled.

This option can be selected even when the Teletext grabber has not yet generated any output. In this case you'll see a screen with the nxtvepg logo and a note to wait for data acquisition. As soon as any EPG information could be extracted, it is shown in the display. You can check on state of acquisition using the "statistics" popup windows also available via the Control menu.

This option is equivalent to manually merging XMLTV files and checking the "Add all Teletext EPG data" option, except that you can't use that way until there is at least one XMLTV file.

Enable acquisition

Toggles EPG acquisition via the TV card on or off temporarily. This option is grayed out if you do not have a TV capture card or if the teletext grabber is disabled (see "CONFIGURE MENU" section "Teletext grabber").

When starting the browser, acquisition is enabled automatically while the respective option in the teletext grabber configuration is enabled. You can suppress automatic start temporarily with the -noacq command line switch, or permanently by disabling auto-start in configuration menu. Switching off acquisition temporarily allows other applications (e.g. a TV application or teletext viewer) to use the TV card while you browse the database, if you have only one TV capture card.

You will get an error message if the device is already busy for a different application, or if you don't have permission to access the device (UNIX, see also "FILES"). If you're experiencing problems that might be hardware or operating system related, test with a TV application or teletext decoder first, because these usually allow for easier debugging (e.g. due to the visible TV image). See also "GETTING STARTED".

UNIX: Acquisition can also been switched on and off automatically (i.e. from a shell script) by sending signal HUP (e.g. with the kill(1) command) to any of the nxtvepg processes or threads. If you're using a daemon for acquisition (see the next command) you have to send the signal to one of the daemon processes/threads. To simplify this, the pid of the process which needs to be signaled is stored in /tmp/.vbi.pid while the device is in use.

Connect to acq. daemon

Connect to or disconnect from an acquisition daemon, running in the background on the same host, or somewhere else in the network. This option is enabled only if the teletext grabber is configured (see "CONFIGURE MENU" section "Teletext grabber").

The address of the daemon and other parameters are configured in the Client/Server menu (see "CONFIGURE MENU", section "Client/Server"). By default the daemon is started on the local host. The main advantage of using the daemon is that you can keep running acquisition permanently in the background, even if you terminate the browser, or on UNIX even the X11 server (i.e. the windowing system). On M$ Windows the daemon is terminated when you log off.

If you attempt to connect, but no daemon is running, you'll be offered the option to automatically start the daemon and retry the connect, provided you have configured server hostname localhost. The daemon will be started with the same database directory and rcfile as the browser.

Note that disconnecting from the daemon or terminating the browser does not stop the acquisition and hence does not free the device. If that's what you want, choose the Enable acquisition command instead, which terminates the daemon. Of course this option only is available if your daemon is running on the same host and with the same user id as the browser process.

View statistics/timescales

The following commands open windows with statistics about the databases and acquisition progress. See "STATISTICS" for details.

View coverage timescales

Toggles the timescale window for the browser database. The window reflects for each network included in the selected database, which time ranges are covered by programme information. While acquisition is working on the database, you can watch how more and more of the scales get populated. See also "STATISTICS", section "Timescale popup window".

View database statistics

Toggles the browser database statistics window, which informs you about number of program entries in the database, fill percentage, expiration percentage, date of last update etc. If the acquisition is working on the same database, it also shows a high-level state and progress of acquisition. See also "STATISTICS", section "Database statistics".

Teletext grabber statistics

Toggles the acquisition statistics window, which informs you about the current state of acquisition as well as statistics of teletext packages received from the currently received TV networks. See also "STATISTICS", section "Teletext grabber statistics".

Export as text

Open a dialog that allows to export the complete database into a text file. Each line in the file will represent one item in the database. The items' different fields are separated by TAB characters; the line is terminated by a single new-line character (no line feed character, even on Windows). In some cases missing values are represented by \N which is the MySQL NULL identifier (currently only used for the VPS/PDC field).

Paragraph breaks within the description text are represented as text " // ". In a merged database, paragraph breaks between description texts originating from different providers are represented as " //%// . When using the texts for display, the first should be replaced with a single newline character, and the latter with either dual newline, or a horizontal ruler.

The generated text file can be loaded directly into a relational database. It's not formatted for viewing in a regular text editor. Networks are represented as numerical indices into the network table. Hence this table is required in addition to the programme table. To load them into a database, you need to export them into different files.

For MySQL you could create the following tables:

CREATE TABLE PI (
   netwop smallint(2) unsigned NOT NULL,
   Dstart date NOT NULL,
   Hstart time NOT NULL,
   Hstop time NOT NULL,
   vpspdc_pil datetime,
   parental_rating tinyint(2) unsigned,
   editorial_rating tinyint(2) unsigned,
   editorial_max_val tinyint(2) unsigned,
   sound enum("none","mono","2-chan","stereo","surround","dolby"),
   is_wide BOOL,
   no_video BOOL,
   is_video_hd BOOL,
   is_video_bw BOOL,
   is_new BOOL,
   is_premiere BOOL,
   is_repetition BOOL,
   is_last_repetition BOOL,
   subtitles enum("no","yes","onscreen","deaf-signed","onscreen,deaf-signed"),
   theme_0 text,
   theme_1 text,
   theme_2 text,
   theme_3 text,
   theme_4 text,
   theme_5 text,
   theme_6 text,
   theme_7 text,
   title varchar(40) NOT NULL,
   descr text,
   PRIMARY KEY (netwop, Dstart, Hstart)
);

CREATE TABLE AI (
   netwop_idx smallint(2) unsigned NOT NULL,
   cni smallint(5) unsigned,
   lto_mins smallint(5),
   daycount smallint(5) unsigned,
   alphabet smallint(5) unsigned,
   addinfo smallint(5) unsigned,
   name text,
   UNIQUE netwop_idx (netwop_idx)
);

CREATE TABLE themes (
   theme_idx smallint(3) unsigned NOT NULL,
   category_name text,
   UNIQUE theme_idx (theme_idx)
);

Note that the database can also be exported directly from the command line by using -dump pi, -dump ai or -dump themes. In this case you can use one or more -epgquery options to export only selected channels and programmes (for details see "OPTIONS".)

Export as XMLTV

Open a dialog that allows to export the complete database in XML format, as defined by the xmltv.dtd version 0.5 (see http://xmltv.org/) The generated file contains both the channel table and the complete TV schedule, including any networks you might have suppressed from the listing inside nxtvepg.

Hint: If you want to restrict the amount of exported data, configure a merged database. This is possible even for a single provider. This way you can exclude certain networks or attributes, e.g. to omit theme categories from the output (see the "Configure" sub-menu in the merge configuration dialog.) See also below for options when exporting via command line options.

Some TV applications are known to not parse XMLTV timestamps correctly. As a work-around for such buggy applications, there's an option which allows to export dates and times in local time instead of UTC (also known as Greenwich Mean Time or GMT.) If all programme data appears shifted by one or two hours in your TV app's schedule, try this option.

Note that the database can also be exported directly from the command line by using the -dump xml option. In this case you can additionally use one or more -epgquery options to export only selected channels and programmes (for details see "OPTIONS".)

Export as HTML

Opens a dialog that allows to export the complete database or selected programmes into a file in HTML format (Hypertext Markup Language) which can then be loaded into a WWW browser, e.g. Netscape or Opera. This is particularly useful if you want to print out TV descriptions.

At the top of the dialog window you have to enter the output file name; if you don't include an extension, .html is automatically appended. Click on the little folder button to the right for a file selection dialog. Press the Export button to create the HTML document and Dismiss to close the dialog window.

By default the checkbutton All matching programmes, but max ... is enabled. In this mode all programmes that match current filter setting will be exported, but only up the given number of programmes. It's recommended to limit the number of programmes because else very large HTML documents are created which may take a long time to load into your Web browser.

Use mode Selected programme only to export only the programme which is currently selected in the main window. In combination with the Append to file mode this allows to incrementally build a document with exactly your programmes of interest.

In the box below there are three radio buttons with which you can select the output format. If you choose Write titles you'll get a table in the same configuration as in the programme title list in the main window. If you want to have different column types, you can build a separate column configuration by selection Different columns than main window and then pressing the Configure button to select which column types to display.

If you select Write descriptions you'll get for each exported programme a feature summary and description, similar to the info in the lower part of the main window.

If you select Write titles and descriptions you'll get the title table on top and all descriptions separately below. In this mode you can select Add hyperlinks to titles to add hyperlinks from titles in the table to the descriptions.

The look of the generated document is almost entirely determined by use of an internal CSS stylesheet. If you don't like the look you can override it with your own stylesheet. Save it to a file named nxtvhtml.css and put it in the same directory as the generated HTML file. For more information on HTML and style sheets see http://www.w3.org/. If your column configuration contains images (see "COMPOSITE ATTRIBUTES"), you have to put them into a sub-directory called images; also your browser has to support the PNG image format.

Note that the HTML file can also be written directly from the command line by using the -dump html switch. In this case the number of written programmes can be limited by appending a number to the keyword (e.g. "-dump html:50") and you can use one or more -epgquery options to export only selected channels and programmes (for details see "OPTIONS")

Quit

Close all windows and terminate the application. If you have started acquisition as a daemon, it will not be terminated (see "CONTROL MENU: Connect to acq. daemon").

CONFIGURE MENU

Summary of commands available from the Configure menu:

Teletext grabber

Open a dialog which allows to enable and configure the teletext EPG grabber. See chapter "TELETEXT EPG GRABBER" for an overview of how the grabber works and how the captured data can be used.

The check-button Enable teletext grabber at the top of the dialog is a global switch that disables the grabber and all internal data acquisition when unchecked. Only after checking the button can any of the controls in the dialog be modified.

When button Start acquisition automatically is checked, then the grabber will start EPG acquisition automatically when leaving the dialog with "Ok" and whenever starting nxtvepg afterward. When it is not enabled, you can still start acquisition manually using the Enable acquisition command in the "CONTROL" menu.

The frame labeled "Teletext options" allows configuring details of teletext capture:

Number of TV channels to grab

This option is the most important one in this section, as it determines for which TV channels the grabber will receive teletext and try extracting EPG. The number refers to the TV channel table you configure in the frame below. The grabber will pick the first X number of channels from the table (radio channels are not counted).

You should reduce the number from default 100 to the number of channels that are actually interesting to you to avoid needlessly increasing time for EPG acquisition. On the other hand, if your channel table is not sorted so that most interesting channels are at the front, then you may have to increase the number so that all channels are included.

Note the grabber will not create XMLTV files for channels where no teletext is received. The grabber is not aware of the connection between channels in regular and HD codec, so it will capture duplicate EPG data for these if both are in the given range of the channel table.

Capture page range

This option defines which teletext pages are captured. The grabber will search all the captured pages for TV schedule overview. For reducing detection errors the page range should be reduce to pages where programme data is expected. Currently however this setting applies across all channels, so the range needs to be the union of potential overview pages of all channels.

Capture duration

This option determines the time spent in second for capturing teletext pages from each channel, or each transponder in case of DVB. Note almost all teletext providers make use of so-called "sub-pages" for TV-schedules, which means that multiple page cycles need to be received for obtaining all relevant pages. For some providers this can up to 8 cycles, so that the default value of 120 seconds is already on the low side. If you see gaps in TV schedules for some channels, consider increasing the value.

Keep expired programmes

This option determines the delay after which expired programme data is removed when updating XMLTV files with new programme data. This removal is done automatically during each update so that the file sizes do not grow to infinity. See also filter "Expired Programmes Display" in chapter "FILTERING" for a description how to expired programme information.

The second frame in the configuration dialog determines from where to load the TV channel table. The grabber requires this table for determining the names of the channels to grab from, and their physical frequency so that it can tune them for receiving their teletext data stream. nxtvepg has no means to create or maintain such a channel table. Instead it is expected that you already have created a channel table for use in a TV application. Without selecting a channel table here you'll not be able to enable the teletext grabber.

nxtvepg supports reading channel tables in the format of several well-known TV applications. After selecting a TV-application from the menu, nxtvepg will try to automatically find the path where this application stores the channel table. In case the path is not filled in automatically, or is not filled correctly, please click the folder button next to the Path entry field and select the path manually (for DVB the file usually is named channels.conf). Use the Test button to check if nxtvepg can parse the file successfully. If you do not have a compatible DVB channel table, for Linux you can use package w_scan and run it to generate a channels.conf file either in VDR or mplayer format.

The third frame Acquisition mode allows configuring the strategy used for data acquisition. The different modes are described in section "Acquisition modes" in chapter "TELETEXT EPG GRABBER".

When checking Keep teletext raw capture data, the grabber will create a file with ".dat" extension next to each ".xml" file it creates (see also chapter "FILES". The data files contain teletext page contents as they were received. The files can be opened in any text editor. The content is largely readable, although there are hexadecimal special characters inbetween, representing special character and color selection codes.

The data can be used to analyze errors or artifacts in extracting EPG from teletext. Note you make the connection between XMLTV content and the raw data via page numbers specified within comments in the "<programme>" tags in XMLTV files: There is one comment above the programmme title referring to the overview page where the time and title were extracted from, and another page reference for the description content. For debugging capturing issues, feed the data file into the stand-along grabber version "tv_grab_ttx" that is available at the nxtvepg web site using command line: tv_grab_ttx -debug -verify FILENAME.dat.

TV channel scan

Open a dialog that allows to start a scan across all TV channels for detecting Teletext transmission. The scan can also serve for checking reception on all channels. Results of the scan are for your information only; the scan is not required for operation of the Teletext EPG grabber and its result are not used internally.

Before starting the TV channel scan, you should configure the TV card and a TV channel table. For convenience, two buttons for opening these dialogs are included at the lower right corner of the dialog window. Note that the TV channel scan only works if you configure the internal tuner as input source in the TV card configuration dialog. (See also chapter "GETTING STARTED".)

For old analog TV cards, the scan still supports a frequency band search mode which is selected by checking Channel table radio buttons "Western Europe" (PAL) or "France" (SECAM). In this mode the scan will perform signal detection on all known analog transmission bands and for each one that is found, try to identify the received channel by means of received VPS/PDC and teletext packets. The result is printed for each channel in the message area of the dialog window. This procedure is equivalent to how the initial channel setup in analog TV sets used to work. The mode is not useful though for nxtvepg, as the list of found channels is not stored by nxtvepg.

Therefore, select the option Load from TV app instead. Press Start scan to start the scan; this will temprarily suspend the Teletext EPG grabber for the duration of the scan, if it was running. In channel table-based mode the scan will visit exactly the frequencies of the TV channels listed in the configuration of the TV application you selected. For each of the channels, nxtvepg will spend a few seconds receiving teletext and VPS/PDC and then print what it found in the message area. In case of DVB, it may also report if the channel does not contain a PID for a teletext stream, which means it definitely does not transmit teletext. Note for DVB, channel results may appear out of order in the message window as nxtvepg will combine channels on the same transponder frequency for speeding up the scan. After the end of the scan, there is a summary about how many channels with teletext were found.

Check the Slow button if you have bad reception on some channels. In slow mode the scanner will not skip channels with "unstable" video signal (i.e. no PLL H-lock within 0.150 seconds) and wait twice as long as normal for everything (e.g. up to 12 seconds for a VPS/PDC channel identification). Note that you can change this setting while the scan is running.

TV card input

Open a dialog where the TV card hardware parameters can be configured.

At the top of the dialog window, the card is selected. Fist check that the radiobuttons show the correct card type: Digital TV for DVB, or Analog TV for PAL/SECAM cards. (NTSC is not supported by nxtvepg). Then the name of your capture card should be shown at the top.

If you have multiple digital or analog cards, you can also choose which one to use, just like with the -card command line option (see "OPTIONS") The drop-down menu will list all card types as configured in the driver. Note that changing the card will reset the input source selection.

Video source allows to choose which video input source to use, i.e. where you have connected an input cable to the TV card. The terms shown in the dialog originate from the driver of your TV-card, so you may see different terms. Usually, terms Tuner or Television refer to input via antenna cable (also known as RF cable, i.e. terrestrial reception, satellite or cable TV); Composite refers to a cinch video cable as used by satellite receivers or cheap video records; S-Video is a variant of Composite with improved image quality (often wrongly called S-VHS cable since it's mostly used by S-VHS video recorders) and easily recognized by the Sub-D connectors (called "Hosidenstecker" in German). Depending o your hardware you may only see a sub-set of these input types, or additional ones (e.g. Radio, which will obviously not work as input for nxtvepg.)

Note if you don't choose a TV tuner as input nxtvepg will not be able to automatically switch to your EPG provider's channel. See also "TELETEXT EPG GRABBER".

The slicer quality option selects between different algorithms by which teletext is extracted from the analog video signal. The simple algorithm works only for excellent TV reception, but has the advantage of using very little CPU resources. The elaborate algorithm (copied from zapping's libzvbi and originally developed for the Linux teletext viewer alevt) is much more error tolerant. When you select automatic acquisition will always start with the simple algorithm but switch to the elaborate one when the transmission error rate is above recommended limits (see also "STATISTICS: Teletext grabber statistics").

Windows only: If you experience data loss due to heavy system load, you can raise the acquisition thread priority (may require special privileges on certain Windows versions.) Default is normal, i.e. the same as for all user applications.

Client/Server

Opens a dialog that allows configuring the connection between browser and an EPG acquisition daemon (i.e. a separate instance of nxtvepg which is running in server mode, see the -daemon command line switch in "OPTIONS"). The daemon forwards newly acquired EPG data to all connected browsers and allows monitoring the acquisition progress.

The dialog contains settings of which some refer to the server-side only, some to the client-side only and some to both server and client. To avoid confusion, there are three radio buttons at the top of the dialog which allow graying out items that do not apply to the client or server respectively (the button selection does not otherwise affect the result of configuration). Note: for server configuration changes to take effect, the daemon must be restarted. If it's running locally, you can do this via the Control menu (see "CONTROL MENU: Connect to acq. daemon")

Enable remote control

Note: this feature is not yet implemented. By enabling remote-control you can stop acquisition, change acquisition mode, TV card parameters or any parameters configured by this dialog in a running daemon via the network connection.

Enable TCP/IP

By enabling connections via the TCP/IP network protocol, you allow connections from remote hosts. Since there's currently no access control in nxtvepg, these hosts can be anywhere in your network, or anywhere in the world if you're connected to the Internet. If you don't have a firewall which prevents incoming connections of untrusted hosts, this mode is highly depreciated, because nxtvepg is not in any way secured against malicious client connections.

Note: on Windows currently only TCP/IP is supported, i.e. you have to enable this option if you want to start the daemon.

Server hostname

Client-side only: this setting identifies the host on which the daemon is running. You can enter either a hostname in "dot.com" format or an IP address in "127.0.0.1" format. If you set it to localhost the connection is automatically established via UNIX domain sockets (i.e. pipes), which is more efficient than TCP/IP. You can still use TCP/IP locally if you set it to the name of your local host, as returned by hostname(1).

Server TCP port

If TCP/IP is enabled, this setting tells server and client which port to use. You can enter an arbitrary number between 1024 and 65535 here, but you have to make sure no other server is using the same port. Make sure you configure the same port number for client and server. The default is 7658.

Bind IP address

If TCP/IP is enabled and your server host has more than one IP address, you can select here on which one to listen for incoming connections. Make sure you use the same IP address as server hostname on client-side, or a hostname that resolves to that IP address. This setting is optional; if you leave the field blank (default) the server will bind to all IP addresses.

Note: on systems that support it, TCP/IP sockets are created in the IPv6 domain (PF_INET6) by default. On some systems (e.g. NetBSD) you cannot connect via IPv4 to an IPv6 server and vice versa, i.e. you need to use the same domain on both ends. If your client only supports IPv4, you can force your server to create an IPv4 socket by binding to an IPv4 address. If you fail to connect to a local IPv6 server via the IPv4 loopback address 127.0.0.1, use the IPv6 equivalent "::1".

Max. connections

This setting limits the number of client connections the server will allow. Once the limit is reached the server will reject further connection attempts.

Log filename

If you enable log generation by the following option, you can choose here where the log will go. Make sure the file is writable to the uid under which the daemon process is running. The file opened and closed for each appended log line (usually there's very low traffic into that file) so you can operate on it (e.g. truncate it) without restarting the daemon.

File min. log level

Here you can choose if log information should be written to a file. If you run nxtvepg with TCP/IP disabled, you don't need to use logging; but if you allow remote connections you should keep log files at "info" level to be able to check which hosts connect to your server.

The following settings are available: "no logging" disables logging; "error" enables logging of internal errors that lead to an immediate exit of the daemon; "warning" additionally enables logging of unexpected events, i.e. internal errors which do not lead to exit; "notice" additionally enables logging of server status changes, i.e. startup and shutdown; "info" additionally enables logging of connection establishment or shutdown.

Syslog min. level

Here you can enable or disable logging to UNIX syslog and Windows application event logging (application name is nxtvepg daemon; this feature is not supported by Windows 95). See UNIX man pages syslogd(8) and syslog.conf(5) or the Windows event log help for details about the syslog facility. The log levels you can choose here are the same as described in the previous paragraph for logging to files.

Note that while network mode is enabled configuration of acquisition mode and TV card input has no effect and no EPG scan is possible. If you use the same rc/ini file for daemon and GUI the changed settings will however be used by the daemon upon the next start.

TV application interaction

Opens a dialog that allows to configure the interaction between a TV application and nxtvepg. You should at least configure your TV application type and path here if you're using one of the supported applications; this is a recommended step during the initial installation to speed up the EPG provider search, as described in "GETTING STARTED".

The first four (only three on UNIX) options allow switching interaction features on or off. If you want to improve startup time on UNIX, turn them all off; in this case nxtvepg does not need to search for the xawtv top-level window (which can take up to several seconds if you have many applications running or a slow connection to your X server.) By default all interaction features are enabled.

General enable

Windows only: the option allows to disable or re-enable the allocation of communication resources, and implicitly to switch off or on all interaction features. While disabled, nxtvepg will be invisible for the TV application. The use of this option is depreciated, as nxtvepg won't automatically free the driver when the TV application is started, and nxtvepg will fail to start acquisition when a TV application is running. Use this option only if you suspect compatibility problems between the TV app and nxtvepg, e.g. if one application hangs or crashes during startup if the other is already running. (Not that such behavior is to be expected, but it's better to be prepared for anything.)

Tune TV button

This option hides or shows the equally named button below clock in the nxtvepg main window. If you're not interested in remote-controlling the TV application, switch it off.

Note the button has a little context menu which opens with right mouse button. It contains several remote controls; which one actually work depends on the TV application.

Cursor follows channel changes

While this option is enabled, nxtvepg will monitor TV channel changes. Whenever such a change is detected, the cursor in the programme listbox will be set onto the title currently running on that network. During EPG acquisition VPS/PDC is used to exactly determine the current programme (only on networks which support VPS/PDC); however if the nominal running time is in the past it's currently not possible to display the programme in the listbox. This info may however be sent to the TV app (see next option).

If you have just a network filter enabled, it will be switched to the new network so that you'll get a complete listing of that network's programmes, starting with the currently running one. This works even when you have excluded this network in the network selection configuration. If there are more or other filters than network enabled, then they will remain unchanged. If the current programme on the new network does not match this filter setting, then neither cursor nor listbox content will be changed.

Display EPG info in TV app

While this option is enabled, nxtvepg will monitor TV channel changes. During EPG acquisition VPS/PDC are also monitored to determine newly starting programmes. VPS/PDC also allows to detect channel changes on an external input source, e.g. a satellite receiver connected via the Composite socket.

After a change of channel or current programme title, the info about the currently running title will be displayed in the TV application. On Windows it's entirely up to the TV application how this information is displayed.

On UNIX the display format can be selected by the following radio buttons:

Separate popup

With this option nxtvepg will generate a small popup window and put it right beneath the xawtv window. The blue area in the small bar on top represents how much of the (nominal) running time lies in the past.

Video overlay

With this option nxtvepg will generate a similar popup, however it's placed on top of the video image (please note that this option only works properly with XFree86 version 4 and the XVideo extension; use the xvinfo command to check if your server supports this feature). You can change fonts and colors in this popup via X resources (see "FILES" for details.)

Video overlay, 2 lines

This option is identical to the preceding one, except that it writes running time and title in separate lines and additionally contains the percentage of expired running time.

Xawtv window title

With this option the info will be sent to xawtv and displayed in the window title. Except for this last option, you can configure the desired display duration with the slider at the bottom of the dialog. A duration of zero means the display will never be removed.

Use external application

Finally, with Use external application an arbitrary external application can be invoked to display the information. Title and runtime information can be passed on the command line, in the same way as for external commands in the context menu (see "CONFIGURE MENU", section "Context menu configuration")

In the middle of the dialog there's one line that indicates the current TV application connection status. It contains the name of the connected application, or not connected either if no TV application is running or if it doesn't support interaction with nxtvepg (see also "GETTING STARTED: Configuring a TV application".) You can connect to different applications than configured below, but if the network names are not synchronized with nxtvepg, the interaction will not work optimally (i.e. nxtvepg might not be able to identify all networks, and hence not be able to provide programme titles).

In the lower part of the dialog window you can configure type and path of your preferred TV application. This information is used to access the TV app's channel table (i.e. TV tuner frequencies and station names) by the Teletext grabber, by the "TV channel scan" (see "CONFIGURE MENU", section "TV channel scan") and by the network name configuration dialog (see "CONFIGURE MENU", section "Network names").

After changing the selection, you can press the Test button to check if nxtvepg can parse the channel table correctly. It will complain if it fails to open the file or registry key and if no channels are found. After the test was successful, you should open the network names configuration dialog and synchronize network names with those of your current EPG provider. (Note the latter is not needed when using the Teletext EPG grabber, as it always uses the names in the channel table for the generated EPG.)

If your TV application is not supported, choose none. (If it's a freeware application feel free to mail me a download URL and I will consider supporting it. However I will not support proprietary closed-source software, unless on request by the author.)

Note that not all of the TV applications listed in the popup menu can currently interact with nxtvepg. The interaction requires modifications in the TV applications; it's up to the respective authors if they want to implement these. (If you are an author of a TV app, feel free to mail me if you want to add EPG support to your application; a demo application and reference implementation source code are available on the nxtvepg home page.)

Select attributes

Open the programme attribute display configuration dialog, which allows to select which attributes are displayed for the listed TV programmes. In the listbox on the left of the dialog window there's a list of all available attribute categories, e.g. title, running time, weekday, TV network name, ratings, ... i.e. mostly the same which are available for filtering. You can create your own attributes to extend this list with the dialog described in the next chapter.

The listbox on the right contains the types currently selected for display. The topmost entry appears on the left side of the listbox. Press Apply to refresh the browser listbox with the new column selection and save the new configuration to the config file.

In the "single list" layout (see "CONFIGURE MENU", section "List layout") each attribute has it's own column in the TV schedule and and associated filter menu in the button on top of the column (provided column headers have not been disabled, see "CONFIGURE MENU", section "Show/Hide".) You can change the width of each column by moving the mouse pointer to the very right of the menu button and then dragging the border to a new position while keeping the left mouse button pressed down.

In the "separate network columns" layout, attributes are printed beneath each other in separate lines in the TV schedule's network columns, unless you select No new line after element while the respective attribute is selected in the right listbox. Empty rows are automatically suppressed, e.g. in contrary to the "single list" layout the number of attributes actually displayed may vary. This is particularly useful for user-defined attributes, e.g. you could specify that theme categories are only printed for movies to keep the listing more compact.

Attribute composition

Open the configuration dialog for composite attributes, which allows to create new column types for the "single list" TV schedule layout (see "CONFIGURE MENU", section "List layout") or new rows respectively in the "separate network columns" layout, which can afterwards be selected in addition to the predefined attribute types (e.g. "Title" and "Theme") as described in the previous chapter.

For a general description of composite attributes see "COMPOSITE ATTRIBUTES". This chapter only describes usage of the configuration dialog. This chapter also assumes you're familiar with the concept of filter shortcuts (see "FILTER SHORTCUTS") and reminders (see "REMINDERS")

The dialog consists of three sections: at the top to the right there is a drop-down menu which lists all currently defined composite attributes. Here you select which attribute definition you want to edit. Below to the left is a list of shortcuts and reminder groups and 4 buttons to edit the list. On the right side of the shortcut list there are various controls for defining how programmes matching shortcuts or reminder groups should be displayed.

Note that there are dependencies between those sections: when you change to a different attribute definition with the drop-down menu at the top, the rest of the dialog is immediately updated to display the current definition of the composite attribute (you'll get a warning if there any unsaved changes in the previous assignments). Also, when you select a shortcut in the listbox, the display attributes at the right are updated.

To create a new composite attribute, you will start by selecting the Create new definition command in the menu at the top right of the dialog window. You should give the label right away, so that you can keep your definitions apart, see "CONFIGURE MENU", section "Select attributes". You should also assign a column header text (only used in the "single list" layout), which will appear above the programme list in the main window; you'll probably use a shorter text here than in the label.

Then you add one or more filters to the list by use of the Add shortcut or Add reminder drop-down menus to the left of the listbox. New entries are always appended at the end of the list, but you can change the ordering by use of the up/down arrow buttons. To remove a shortcut or reminder group from the list, first select it then click the Delete button or key. Note: ordering is important when a programme is matched by more than one shortcut, or if you mix shortcuts with reminder groups, because the display format will be determined by the first matching entry in the list, starting at the top (see also "COMPOSITE ATTRIBUTES".)

At the right of the shortcut list there are controls which defines what's displayed in the programme list depending on a shortcut or reminder match (for programmes which don't match any of the given shortcuts nothing will be displayed, unless you have a *no match* entry.) By default a match is displayed as the name of the matching shortcut or reminder group, but you can easily change that with the controls to the right of the listbox. The choices are: freely defined but static text, one of the pre-defined images or one of the programme's attributes (i.e. if you select Time the programme's start time will be displayed).

In case you chose to use text (including attributes), you can select bold, underlined or over-strike font and the text color. For all types you can also select a background color. Colors can be applied either just to the user-defined attribute itself, or the entire column (in single list layout; or the entire element in grid layout) The resulting appearance is shown in a Text sample above the controls. These display options can be configured separately for every shortcut match. An exception is the entire-column background color; if such a format is found in multiple attributes, the last one counts.

When you want to try out your attribute definition, press the Apply button at the bottom. The definition is saved and the browser content is updated. If the attribute is not currently used in the browser, you're offered in a popup message to automatically append the attribute to the TV schedule. You can later change it's position by using the Select attributes configuration dialog.

There's also a Delete button at the bottom which allows to remove obsolete definitions. If the composite attribute is still displayed in the browser, it's automatically removed. Note that a deletion cannot be undone, i.e. the information is lost irrecoverably.

Select networks

Open the network selection dialog. It allows to permanently suppress TV networks in a provider's listing, e.g. if you can not receive the channel. You can also change the order of the networks, e.g. to put your favorite networks at the top of the filter menus.

This window has two lists: on the left you'll find all networks that are covered by the provider in their original order, on the right those that are selected for the programme listing in your preferred order. By default, both lists will have exactly the same content. If you want to exclude networks, select them in the right list and press Delete. You can always include them again by selecting them in the left list and pressing Add. You can change the order in the right list by selecting one or more networks and pressing the up or down arrows.

At the bottom of the dialog window there's an entry field named Air times that allows to limit the program listing for a network to a given time frame. For example if you receive Arte only from 19:00 until 07:00 o'clock, select "Arte" either in the left or right list, then enter "19:00" and "07:00" in the fields (make sure to always use 4 digits and the separating colon). Programmes that fall completely outside that window will not appear in the browser window. If you want to undo the limitation, enter 00:00 until 00:00 or any other equal time values.

Note: you can also operate this dialog (and all other dialogs with similar listbox selections) with he keyboard: use the TAB key or the mouse to move the keyboard input focus to the left or right listbox. Use the cursor up/down keys to select an item; hold down SHIFT to select multiple items. In the left list, press Return to add a network to the right list. In the right list, press the Delete key to remove a network, or press CONTROL and the up/down cursor keys to change the selected items' position in the list.

Network names

Open the network names configuration dialog. Its main purpose is synchronizing network names between nxtvepg and your TV application. This is required because the network name is used in communication when you use the Tune TV remote controls, and as well for channel change notifications by the TV applications. For many networks there will be no need to change anything, but for some there exist different variants, e.g. in Germany "Super RTL" vs. "S-RTL" or "MDR3" vs. "MDR".

If you are using one of the TV applications supported by nxtvepg and want to use the "Tune TV" button and other interaction features, then you should configure the TV application via the TV app. interaction dialog in the "CONFIGURE MENU". Otherwise you can use the dialog to freely edit channel names according to your personal preference.

On the left side of the network name dialog you find a list of all networks used in the currently loaded or merged XMLTV files. When opening the dialog for the first time, and a TV application is configured, nxtvepg will automatically synchronize names with those used in the TV application. This means that when there is a channel name in the TV application that only differs in spaces or non-alpanumeric letters from the one in XMLTV, then the name from the TV application is used. Names for which no obvious match is found are kept undhanged and marked in red text color. If no TV application is configured, the network names used by your currently selected EPG provider are taken directly from the XMLTV files In case of a merged database, the channel name found in the first merged XMLTV file is used.

On the right side, you are offered three ways to change the channel name used by nxtvepg: Top-most is a plain entry field where you can type in an arbitrary name. Below is a listbox which lists similar channel names found in your TV application's channel table. The bottom-most frame lists the original names used in the XMLTV file. If you double-click on an entry in either list, the name is copied to the entry field at the top.

If you want to save the changed list, leave the dialog with Save, else use Abort.

Note: If you receive channels that carry multiple networks, e.g. in Germany "Arte / Kinderkanal", it's recommended to include all networks' names in the network name on side of the TV application, separated by a slash. The slash is recognized as separator by nxtvepg and all resulting segments can be used as network names.

Context menu configuration

Open the context menu configuration dialog which allows to change the order of automatically generated menu entries or to extend the popup menu with user-defined external commands (for a general description of the context menu see "CONTEXT MENU").

At the top of the dialog window there's a list of titles of all currently defined menu items. When you open the dialog for the first time, you'll see only pre-defined "pseudo commands" (such as "Add programme filters".) These don't show up like that in the context menu, they just represent menu commands which are automatically inserted in their place at run-time, depending on the currently selected programme entries and current filter settings (e.g. to add a filter for the network of the currently selected programme.)

As usual, you can change the ordering of items in the list by selecting an item and then clicking the buttons with up/down arrows. To remove an entry, select it and press Delete. If you make an error you can leave the dialog with Abort; changes aren't applied and saved until you leave the dialog with Ok.

The Add new menu button allows to insert a new menu item below the currently selected one:

External command

Start an external application with the given command line parameters. This is equivalent to typing a command into a UNIX shell or using Run command in the Windows Start menu. Command line parameters may use variable substitution as described below. To allow sharing the same nxtvepg configuration file on UNIX and Windows, there are different types, i.e. UNIX or Windows. Commands are only included in the context menu if the platform matches the command type.

The dialog's entry field labeled Title defines the text which will be included to the popup menu. The field labeled Command defines the command line

TV application remote command

Send the given command line to an attached TV application, e.g. to switch TV channels. Variable substitution can be used here, too. How the command is sent depends on the TV application; when no TV app. is connected, such entries are automatically disabled (see also "CONFIGURE MENU", section "TV application interaction") For example

setstation ${network}

would create a command that switches the TV app's channel to that of the currently selected programme (i.e. the same what the Tune TV button does). You should refer to the documentation of your TV app to see which commands it supports.

Menu title and Menu separator

These can be used to organize the menu contents into groups. In case of menu titles, the dialog's entry field labeled Title defines the text which will be included to the popup menu.

Add/Undo programme filters

This menu entry will be replaced by automatically generated commands to manipulate filter settings. See "CONTEXT MENU" for details.

Add/remove reminder

This menu entry will be replaced by automatically generated commands to manipulate the reminder list. There are two versions of the entry: if you select the extended version, an additional entry will be included which allows to select reminder groups (only useful if you're using multiple groups, see also "REMINDERS".)

When you press the menu button Add Example a list pops up which contains a few example commands which can be copied into the title and command entry fields.

As mentioned above, external commands and TV app. remote commands allow to include placeholders enclosed in ${} which are replaced by attributes of the programme selected in the browser listbox at the time the context menu command is invoked. The following is a list of such formal variables The meaning of the variables should be self-explanatory, except possibly for CNI: this is a hexadecimal network code, and e/p_rating: these are editorial and parental ratings respectively.

${title}
${network}
${start}
${stop}
${relstart}
${duration}
${CNI}
${description}
${themes}
${VPS}  or  ${PDC}
${e_rating}
${p_rating}
${sound}
${format}
${digital}
${encrypted}
${live}
${repeat}
${subtitle}

Start and stop time related keywords can optionally be followed by either a plus or minus sign and a time offset. The offset value is assumed to be given as minutes. For relstart and duration the precision can be changed by means of the format (see below.) Example: to print the start time minus 5 minutes (e.g. to start a recording 5 minutes earlier) use ${start-5:%H:%M}

The keywords can optionally be followed by a colon and an output format specification. Options depend on the type of variable substitution:

Start, stop and VPS/PDC times

All options defined in the strftime(3) manpage are available; default is %H:%M-%d.%m.%Y (hour, minute, day, month, year).

Relative start time and duration

You can choose between minutes (default) and seconds by appending "m" or "s".

Theme categories

You can choose between numerical and textual output by appending "n" or "t". Use command line option -dump themes to get a list of theme categories (see "OPTIONS".)

For all other variables modifiers are currently ignored.

On UNIX the resulting sub-strings which replace the formal variables are always enclosed in single quotes, because the command line is passed to a system shell for execution (/bin/sh, i.e. the Bourne Shell by means of the system function; see also system man pages sh or bash) and there are many characters with special meaning. Single quotes inside of the substituted string are correctly escaped.

Example: The command line

plan ${start:%d.%m.%Y %H:%M} ${title}

could for example on UNIX systems result in

plan '22.08.2001 13:05' 'Fish '\''n'\'' Fun'

On Windows only single- and double quotes and space characters are escaped with a backslash. Hence the above example would result in:

plan 22.08.2001\ 13:05 Fish\ \'n\'\ Fun

Note if you want to prevent the backslash inbetween date and time (if the called program doesn't understand it), you can simply use two separate substitutions for date and time. Example:

plan ${start:%d.%m.%Y} ${start:%H:%M} ${title}

Themes language

Select the language for programme themes (i.e. content category, see "FILTERING") in the main window and the filter menu. By default it's set to automatic; in this case the language is derived from the selected provider's database. Please note that the language of the menus, help etc. currently can not be changed from English.

Show/Hide

Toggle visibility of various components in the main window:

Show shortcuts

Toggle visibility of the shortcut listbox at the left of the programme list. When you unmap both the shortcuts list and the network list below, the clock and reset buttons are also unmapped so that you get only the programme list.

Show networks (left)

Maps or unmaps the network filter listbox below the shortcuts list, or below the clock if you've unmapped the shortcuts list.

Show networks (middle)

Maps or unmaps the network filter listbox between shortcuts listbox and programme list.

Show layout button

Maps or unmaps the Grid layout checkbutton below the shortcuts or network list in the main window (see also "CONFIGURE MENU", section "List layout"). If you're permanently using one or the other layout, you will probably want to unmap this button. (It's mainly present to make users who upgrade from older versions aware of this new option.)

Show status line

Maps or unmaps the database and acquisition status line at the bottom of the browser window.

Show column headers

Maps or unmaps the browser listbox column header menubar, i.e. the row of menu buttons above the programme list in single list layout.

Show weekday scale

Maps or unmaps the weekday scale to the right of the programme list. (Note you can configure the looks, i.e. font, colors, width and date format via the resource file nxtvepg.ad or .Xdefaults on UNIX, see "FILES")

Hide on minimize

Windows only: When this option is enabled, the main window's entry in the task bar is removed when it's minimized or when the program is started with the -iconic command line switch. Instead an icon is added to the system tray in the task bar. A double-click on the tray icon de-iconifies the main window. A click with the right mouse button opens a little popup menu. The entries in this menu have the same meaning as the equally named ones in the control menu (see "CONTROL MENU").

List layout

Select layout of the programme list in the main window:

Single list for all networks

This is the original layout (the only layout until nxtvepg version 2.4) in which all programmes of all networks are presented in a single list, sorted by start time.

Separate columns for each network

In this layout programmes are still sorted by start time, but presented in separate columns for each network. Schedules of different networks are aligned, so that programmes which run at the same time are approximately at the same height.

You can join several columns in a single column via the Control menu (meant for networks which share the same channel; use this in conjunction with air times restriction as described in "CONFIGURE MENU", section "Select networks".) The control menu is part of the drop-down menu below the button at the top of the column. This menu also holds commands to increase or decrease the number of visible columns.

In both layouts you can select which types of attributes are printed for each programme by clicking on the icon in the button row at the top of the list (unless column header buttons are hidden.)

FILES

Files used on UNIX systems

$HOME/.config/nxtvepg/nxtvepgrc

Default for the configuration file where all personal settings are stored. Note a different path and file name can be specified with the -rcfile option (see "OPTIONS").

$HOME/.cache/nxtvepg/

Directory path containing one file for each network from which Teletext EPG is grabbed. The directory can be changed with the -dbdir command line option (see "OPTIONS").

Files written by the Teletext EPG grabber have names in format ttx-SID.xml, where "SID" is the DVB service ID taken from the respective channel's entry in file channels.conf. (The SID is used instead of the clear-text channel name so that the file remains accessible across name changes.) The file content is in XMLTV schema. A separate file is created for each channel from which data is grabbed.

/dev/dvb/adapter0/frontend0, /dev/dvb/adapter0/demux0

Device files from which teletext data is being captured during acquisition when a Digital TV (DVB) device is selected in the TV card configuration dialog. The first device file is used for tuning and the second for receiving data streams. The adapter directory post-fix can be specified with the -card command line option (see "OPTIONS").

/dev/vbi0, /dev/vbi1, etc.

Device files from which teletext data is being read during acquisition when an analog TV capture card is selected. The device index post-fix can be specified with the -card command line option (see "OPTIONS").

You must have read/write access to these files; by default this is not the case for many Linux distributions for security reasons (since you might have connected a WebCam and mike and someone could spy on you from remote). However on a single-user system it's safe to make them world-readable and writable, i.e. in a root shell enter:

chmod 666 /dev/vbi

Alternatively you can make yourself a member of a group in /etc/groups which has access to the devices or create such a group.

/dev/video0, /dev/video1, etc.

On Linux kernel series 2.4 and earlier (i.e. before revision #2 of the video4linux API) these device files are used to select the input source (e.g. TV tuner or one of the composite or S-Video sockets) and tuner frequency for VBI reception, unless you choose the passive acquisition mode. The index post-fix can be specified with the -card command line option. This device must be readable and writable.

The device is only kept open during a provider search (see "CONFIGURE MENU", section "TV channel scan"). Else, it's just opened shortly to set the input source and tuner frequency. If the device is busy (e.g. while you watch TV), acquisition starts on the currently selected channel and automatically follows any externally controlled changes (this will be reported, e.g. in the status line at the bottom of the browser window, as forced passive acquisition mode, see "STATISTICS: Status line").

Note: it's mandatory that the video device has the same index as the VBI device. If you have a video device at index 0 which does not support teletext (a webcam, for example) the VBI device belonging to video device #1 may appear at index 0. You should force the driver to assign device index #1 to the VBI index. On Linux this is possible by using insmod parameters in /etc/modules.conf, e.g. for bttv:

options bttv video_nr=1 vbi_nr=1

/dev/v4l/vbi0, /dev/v4l/video0

If you have enabled devfs in your Linux kernel, the VBI and video devices will appear in a sub-directory. nxtvepg automatically detects the existence of this directory and will search the devices there instead of the regular paths.

/tmp/.vbi0.pid, /tmp/.vbi1.pid, etc.

This file contains the PID of the nxtvepg process (or the acquisition slave process unless threading is used) whenever a VBI device is kept open. The process can be forced to free the device by sending it signal SIGHUP, e.g. from a wrapper script around a teletext decoder. An example which works with all shells:

kill -HUP `cat /tmp/.vbi0.pid`

Note that the daemon is not kept alive when acquisition is disabled, so that sending HUP to the daemon equals sending TERM. You can restart acquisition by starting a new daemon. The browser attempts to reconnect every 10 seconds when the connection was broken, but you can also trigger an immediate reconnect be sending the GUI process SIGHUP.

To restart acquisition in non-daemon mode, signal again with SIGHUP, either to the acquisition slave process or the browser process.

/tmp/nxtvepg.0

This non-regular file (socket) is created by the daemon to allow local client connections via UNIX domain sockets. The same socket can be used for more than one client connection. It's deleted when the daemon terminates (unless the daemon crashes or receives an "uncatchable" signal like the infamous signal 9 aka KILL). See also "CONTROL MENU: Connect to acq. daemon".

.../channels.conf

DVB only: The Teletext EPG grabber requires a channel table which contains a TV channel table, indicating names, frequencies and the PID of the teletext data stream. nxtvepg does not create such files; you need to use an external DVB channel scan application such as w_scan for that and point nxtvepg to use its output. Currently, nxtvepg supports the format used by VDR and the format shared by mplayer, Kaffeine, xine, Totem and others. See also "CONFIGURE MENU", section "TV application interaction".

$HOME/.Xdefaults

This file is usually loaded into the X server at startup (or during login) by use of the xrdb command. It contains a series of parameter assignments called X resource definitions for any number of applications. Note: depending on your X11 startup scripts this file may have a different name, e.g. .Xresources. The file could be used to change the "look" of almost every element in every dialog window (within limits, because some options are hard-coded) or the look of entire widget classes, like menus or buttons. However that's highly implementation dependent and generally not very useful, hence depreciated.

Defaults for all officially supported options are listed in the so-called "app-defaults" file Nxtvepg.ad which is usually installed in /usr/X11/lib/X11/app-defaults (the .ad extension is omitted during installation.) You should not change values there however, because they would be overwritten when you install new versions. Instead copy changed lines into your .Xdefaults file (without the leading comment ! sign.) Note you have to restart nxtvepg for changes to take effect. When X11 is already running you can override individual settings with xrdb like this:

echo "nxtvepg*text_bg: #E9E9EC" | xrdb -merge

Color values can specified either symbolically (e.g. "red") or as hexadecimal RGB values in #RRGGBB format. A special case are the 7 colors for weekday background colors in the main window's date scale: it's resource value consists of a comma separated list of 7 colors.

Fonts must be specified as triplets of family, size (use negative values to specify the size in pixels and positive values for sizes given in points) and appearance (only "normal" or "bold" are recommended). Lines starting with a ! sign are treated as comment and hence ignored. Entries that do not adhere to this syntax are silently discarded.

Files used on Windows systems

nxtvepg.ini

Configuration file where all configuration and personal preference settings are stored. By default this is created in the working directory, but a different path and file name can be specified with the -rcfile option (see "OPTIONS").

Nxtvepg.ad

Allows to change the application's appearance, i.e. colors and text fonts. The format and content of the file is identical to the .Xdefaults file described in the UNIX section.

ttx-SID.xml

Files written by the Teletext EPG grabber have names in format ttx-SID.xml, where "SID" is the DVB service ID taken from the respective channel's entry in file channels.conf. (The SID is used instead of the clear-text channel name so that the file remains accessible across name changes.) The file content is in XMLTV schema. A separate file is created for each channel from which data is grabbed.

vbi_map.dat

This hidden file is used to set up shared memory to allow information exchange between nxtvepg and an attached TV application. It's automatically removed when nxtvepg terminates and should never be accessed (i.e. being written to or removed) by external applications. The file is not created when TV app. interaction is disabled (see "CONFIGURE MENU", section "TV application interaction").

AUTHOR

T. Zoerner tomzo (at) users (dot) sourceforge (dot) net

The best way to provide feedback is via the discussion forum at the nxtvepg homepage. Please see the README file for instructions about the information that must be included in a bug report (for example, a bug reporting only "feature does not work" will not suffice.)

Many thanks to Néo for providing the MS windows installer, the K!TV instruction manual and for the French translation of several web pages; to Kurt Lettmaier for his valuable feed-back and suggestions; to Kurt Lettmaier and Olaf Noehring for the German translation of the manual; to Thierry Ménétrier and Peter Rolf for their valuable feedback and suggestions; to Simon Barner for the FreeBSD port; to Matthieu for the French translation of PDC theme descriptors; to E-nek for the DScaler driver port and cooperation in develepment of the TV application interaction; to John Adcock for the DScaler driver; to Jan Schuster for beta testing nxtvepg 0.7.0; to Mario Kemper for the NetBSD port and early beta testing; to "Mario's brother" for beta testing the first Windows port; to Gerd Knorr for xawtv and maintaining the Debian and SuSE nxtvepg packages; to Ralph Metzler for his teletext decoder; to Edgar Toernig for the Latin-1 conversion tables in alevt; and last but not least to the authors of bttv and v4l for their excellent work, and the authors of the Cygwin GNU and XFree86 port, without which nxtvepg would never have been ported to M$ Windows.

Historical note: Originally, nxtvepg was developed as a decoder for the nexTView EPG as defined by the European Telecommunications Standards Institute (ETSI) in ETS 300 707: "Protocol for a TV Guide using electronic data transmission". Up to apx. 2012, nxtvepg enabled you to obtain free TV programme listings for all of the major networks in Germany, Austria, France, Belgium and Switzerland. However, Nextview EPG is not transmitted via digital TV signals (i.e. DVB), as these use a different EPG standard with similar features. Therefore this standard became obsolete once analog TV transmission was switched off and has been removed from nxtvepg in release 3.0.

COPYRIGHT

Copyright (C) 1999 - 2011, 2020 - 2023 by T. Zoerner. All rights reserved.

Additional copyrights apply to portions of the code herein. Please see file COPYRIGHT and source file headers for details.

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 WITHOUT ANY WARRANTY; without even the implied warranty of merchantability or fitness for a particular purpose. See the file COPYRIGHT for more details.