FreeGuide Readme

Contents

Introduction

FreeGuide is a TV guide programme. It uses parser programmes to extract TV information from web pages and stores them for viewing without the need to connect to the Internet. The viewer allows the user to view television listings and create customised TV guides by selecting programmes and by building up a favourites list.

It works with listings for Canada, Denmark, Finland, Germany, Hungary, Italy, the Netherlands, New Zealand (Linux only), Spain, the UK and the US.

FreeGuide is written by the FreeGuide contributors (copyright 2001-2003). Please do send code, ideas, bugs and comments to freeguide-tv-devel@lists.sourceforge.net. FreeGuide's home page is at http://freeguide-tv.sourceforge.net. You can contact the lead developer, Andy Balaam at the Centre for Computational Neuroscience and Robotics (CCNR), University of Sussex, Falmer, Brighton, UK.

FreeGuide uses the XMLTV parsers (and file format) developed by the very friendly people at XMLTV (http://membled.com/work/apps/xmltv/ and http://sourceforge.net/projects/xmltv). It also contains snippets of other code borrowed from other GPL projects: see the contributors page for info.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This licence is contained in the file COPYING

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 US

Installing FreeGuide

FreeGuide is written in Java, and thus should work on most types of computer. It is developed and tested on Linux and Windows.

Windows users should read the Windows installation docs.

Linux and other Unix-like users should read the Linux installation docs.

Other people should try following the Linux instructions, but note that you will definitely need Java 1.4, which may be a problem on Mac OS.

Using FreeGuide

The first time you run FreeGuide it will check that everything is set up correctly, and allow you to change things if something's gone wrong. If you followed the installation instructions for your platform exactly, but you get an error here, it's a bug - sorry! - contact the developers and we'll sort you out.

If all has gone well, FreeGuide will know what channels you want, but won't be able to show any programmes because you haven't downloaded them yet. When it starts it will ask you whether you want to go to the download screen. Connect to the Internet, and click Yes. Cross your fingers and wait. If all is well, the listings should eventually download (it can take some time), and you can click OK to start using FreeGuide. If you get the "Execution Error" message, don't panic - click "Continue" and you may find that all has still worked fine. If you continue to have problems, click "Show Output" when you get the execution error, and paste the messages you see into an email to us at freeguide-tv-devel@lists.sourceforge.net and we'll try to help.

Note: if you very quickly get an "Execution Error" message, check that you're connected to the Internet and try again. If you wait quite a while and then get the "Execution Error" message, everything may still be alright - click "Continue" to see.

On the main screen time advances from left to right (click "Go To Now" to see what's on now), and the channels are shown one below another.

The + and - buttons change the day you are looking at, or you can choose a day from the list.

You can click on a programme (making it go grey) to add it to your personalised TV guide for today, which is shown in the bottom section of the window.

You can make programmes highlight themselves by adding them to your favourites list (under the "Tools" menu click "Favourites"). Any programme matching a favourite will be ticked automatically. You can always un-tick programmes if you wish. You can also make a programme a favourite by right-clicking it and choosing "Add to Favourites".

Clicking "Print this personalised listing" will open up your web browser with your customised TV guide, and you can print it by choosing "File" and then "Print" in your browser.

To download more listings, click on "Download Listings".

You can create different sets of channels to display using the "Channel Sets" option on the "Tools" menu. You can choose a channel set with the dropdown list at the top-right of the main screen.

Check out the "Tools" menu to customise FreeGuide and alter various options.

Notes and Troubleshooting

Replacing your XMLTV grabber

If FreeGuide used to work for you and has now stopped, it is probably because the web site it grabs listings from has changed its format. Check the XMLTV page for updated parsers. To replace your XMLTV version:

Can't configure the grabber

If your grabber fails to configure or run because it can't seem to get any data from the Internet, it may be because you need to use a proxy server. In the following replace "proxy.uni.ac.uk" with your proxy server address, and "8080" with the port it uses. On Windows you can find these out from the "Tools" menu on Internet Explorer by choosing "Options", going to the "Connections" tab and clicking "LAN Settings":

With Windows 2000/XP:

With Windows 95/98/ME:

With Linux:

Authenticating Proxies

If you have an authenticating proxy, try "user:password@proxy.uni.ac.uk:8080" replacing "user" with your username and "password" with your password.

Timezones

FreeGuide may benefit from setting your environment variable "TZ" to your time zone. ("EST5EDT" refers to New York timezone, so you'll need to adjust it, e.g to "GMT" for London.) Here's how:

With Windows 2000/XP:

With Windows 95/98/ME:

With Linux:

Grabbing from 2 listings sources

It is possible to make FreeGuide grab the listings from two different listings providers and merge the results for you to view. This might be useful if you want to see listings for 2 different zip codes, for example. To do this you will need to configure your grabber twice, and save the config files as (e.g.) tv_grab_na_1.conf and tv_grab_na_2.conf in the normal directory for XMLTV config files. Then you'll need to go to FreeGuide's "Advanced Options" screen and the "Grabber Command" tab. Instead of what's there you'll need these 3 lines:

"%misc.xmltv_directory%\xmltv.exe" tv_grab_na --config-file "%misc.xmltv_directory%\tv_grab_na_1.conf" --offset %offset% --days 1 --output "%misc.working_directory%\tv-%date%-1.xmltv.tmp"

"%misc.xmltv_directory%\xmltv.exe" tv_grab_na --config-file "%misc.xmltv_directory%\tv_grab_na_2.conf" --offset %offset% --days 1 --output "%working_directory%\tv-%date%-2.xmltv.tmp"

"%misc.xmltv_directory%\xmltv.exe" tv_cat --output "%misc.working_directory%\tv-%date%.xmltv" "%misc.working_directory%\tv-%date%-1.xmltv.tmp" "%misc.working_directory%\tv-%date%-2.xmltv.tmp"

(On Linux you'll need the equivalent. Ask if you need help.)

Missing listings after a successful download

If you grab some listings late in a day, nearing the grabber's idea of the end of a day (e.g. close to 6am for the UK grabber) then you may be told that there are missing listings for that day even though you've just grabbed new listings. This is because the grabbing has started from tomorrow, so what's left of today doesn't have a full set of listings. Don't worry about this - just say "No" and you should be able to see what you need.

Missing favourites after a download

If your grabber works in midnight to midnight time slots, you may find that on the day you do a download, programmes which are favourites and are on after midnight are not chosen automatically. If you click "Reset Choices" in the bottom right, they will be chosen.

Other Notes

You may like to check out our TODO list.

If you use the North American grabber on Linux it will never overwrite listings files that already exist. If you want it to overwrite a particular file, delete it from ~/.freeguide-tv/.

If FreeGuide won't work for you, why not make it work? If you're having trouble, ask us and we'll be glad to help.