-
Notifications
You must be signed in to change notification settings - Fork 2
Installation
-
[MythTV users only] Install and configure MythTV first. In mythtv-setup -> 3. Video Sources -> (your video source) -> Listings grabber, select "No grabber". Perform a channel scan: mythtv-setup -> 5. Channel Editor -> Channel Scanner.
-
Download Shepherd:
wget http://www.whuffy.com/shepherd/shepherd -
Run it:
perl shepherd -
If Shepherd won't run because a "mandatory module" is not found, install it (see "Perl Dependencies") and try again. You may have to install several mandatory Perl modules before Shepherd can run. Shepherd will now install itself and its components (probably into ~/.shepherd/). Most likely, one or more components will fail due to missing Perl modules, but that's fine: we'll fix that later.
-
Answer the configuration questions to select your region. When asked if you want Guided Channel Selection, say yes. Shepherd will then step through each of your MythTV channels, asking you to choose appropriate guide data for each one. Some MythTV channels you won't want guide data for (e.g. radio channels, guide channels, duplicate channels); that's fine. (If you are not a MythTV user, or Shepherd cannot access your MythTV, you will enter Advanced Channel Selection instead to manually enter XMLTVIDs for each channel.) When asked to confirm that you want to create Shepherd's configuration file, say yes.
-
Shepherd will test its components. Some may fail: that's okay for now.
-
Shepherd will ask if you would like to automatically configure MythTV. If you're a MythTV user, this is a good idea, because otherwise it's quite easy to get wrong. Say yes and Shepherd will setup a tv_grab_au symlink, register itself as the default grabber for MythTV, and add itself as a cron job so that your system runs it regularly.
-
Shepherd will ask if you would like to install channel icons. This is optional, and you can do it later if you prefer. If you say yes, Shepherd will step you through a variety of icon galleries to choose from.
-
Shepherd will exit. For maximum functionality, you should now install any missing Perl modules required by components. How to do this varies depending on your distribution: see the [wiki:Installation#PerlDepen dencies detailed instructions] and [wiki:FAQ#HowimportantisittoinstalltheoptionalPerlmodules why this is worth doing]. Essentially, you should attempt to install any modules that Shepherd complains are missing when you do this:
tv_grab_au --check -
To avoid confusion, delete the original Shepherd file you downloaded (leaving the newly installed version in ~/.shepherd/).
Shepherd is now installed. This means that when run, it will create a file of TV guide data (by default: ~/.shepherd/output.xmltv). It also creates a log file at ~/.shepherd/log/shepherd.log. Most users want this guide data to be regularly fed to another program: see the relevant section below on integration with [wiki:Installation#IntegrationwithMythTV MythTV], [wiki:Installation#IntegrationwithFreevo Freevo], or [wiki:Installation#IntegrationwithEyeTV EyeTV].
It's no longer important to choose the "right" user to install Shepherd. (In previous versions, we asked MythTV users to ensure Shepherd's user matched that of MythTV. But this could be tricky to figure out, so we changed it.)
The simplest way to install Shepherd is as whichever user you usually use. If you're concerned about Security, you could create a new user specifically for Shepherd, but be aware that Shepherd is user-specific: once installed for a particular user, it will only run for that user. (This prevents permissions problems.) Installing Shepherd as user "alice" then attempting to run it as user "bob" will begin a fresh install in Bob's directory, to avoid interfering with Alice's.
We do not recommend running Shepherd as root.
Shepherd now has the ability to auto-configure MythTV for you, which eliminates a few common traps. You are asked whether you want to do this during initial configuration, as described above, but you can also (re -)do it with:
~/.shepherd/shepherd --configure-mythtv
This will register Shepherd as 'tv_grab_au' on your system (by creating a symbolic link, usually in /usr/bin/), register itself with MythTV as the default grabber, and set up a cron job so that your system regula rly invokes Shepherd in order to regularly download up-to-date guide data.
Following configuration, MythTV should begin using Shepherd to obtain guide data within a few minutes. (In MythTV frontend -> Information Center'' -> ''System Status'' -> ''Listings Status, you should see "Myth filldatabase is currently running.) It can take a while for Shepherd to complete its first run, even two or three hours.
Note: this routine requires sudo be available for the user. It is not required for any further shepherd running, so can be temporarily enabled if preferred. Information on configu ring sudo can be found in the sudo manpage or here.
For more information, see the [wiki:FAQ#MythTVrelated MythTV section of the FAQ].
If you use multiple sources (e.g. free to air plus cable TV), then you can run auto-configuration as normal, but then modify the mythfilldatabase line (with "crontab -e") to look something like this:
44 * * * * tv_grab_au --quiet && mythfilldatabase --update --file 1 ~/.shepherd/output.xmltv --quiet && mythfilldatabase --update --file 2 ~/.shepherd/output.xmltv --quiet
Here mythfilldatabase'' is invoked twice, once for each source. The "''--update" option prevents MythTV from creating channels on the wrong source.
Note for Ubuntu users: Be aware of this bug, which can cause silent failure of cron jobs on systems with no mail transport installed.
The alternative to a cron job is to have MythTV automatically run Shepherd, via Utilities/Setup'' -> ''Setup'' -> ''General'' -> ''Mythfilldatabase -> "Automatically run mythfilldatabase" in mythfrontend.
This is no longer recommended. The main problem is that MythTV may not invoke Shepherd as the user you expect: it might be your own user, it might be mythtv, or it might be root, depending on your system. Thi s can lead to Bad Things, such as root creating files that your regular Shepherd user cannot modify.
Freevo will use the Shepherd data with a little alteration. In local_conf.py set the XMLTV_GRABBER XMLTV_GRABBER = '/home/tv/.shepherd/tv_grab_au --timeoffset=Auto' (or /usr/bin/tv_grab_au if you have set the symlink) If you have existing xmltv channel id set, use the ones you have already set when running
~/.shepherd/shepherd --configure
Otherwise use any channel id you choose. Test your setup with
freevo tv_grab
Beginning with EyeTV version 3.0.1, EyeTV can use xmltv files as its source for channel and program guide data. However, it is quite picky about how those files must be presented, so it won't quite work "out-of- the-box" with Shepherd. To integrate Shepherd with EyeTV, you need to do the following:
-
install and configure Shepherd
-
install and launch EyeTV
-
in EyeTV's Preferences, select "None" as the TV guide service
-
download the XMLTV DTD and save it (using the file name "xmltv.dtd") in your .shepherd directory
cd ~/.shepherd wget http://xmltv.cvs.sourceforge.net/*checkout*/xmltv/xmltv/xmltv.dtd
-
EyeTV won't recognise the default output file suffix of ".xmltv", so configure Shepherd to produce an output file with the suffix ".xml", e.g.
./tv_grab_au --component-set shepherd:output=output.xml
-
now run (or re-run) Shepherd
./tv_grab_au
-
open the resulting .xml file with EyeTV, either by dragging and dropping in the finder or using the following command line:
open -a EyeTV.app output.xml
-
in EyeTV, set up each channel in your list to use the xmltv guide information (in the Channels list, select xmltv, and choose the matching channel name from the list)
-
you should now see your download xmltv information when you view the Program Guide or your favourite channels list(s) in EyeTV. xmltv information will also be used by any Smart Guides you have set up.
To periodically run Shepherd, set up a sequence of cron jobs, such as the following (these are spaced one hour apart to give Shepherd plenty of time to finish):
01 03 * * * /Users/yourname/.shepherd/tv_grab_au > /dev/null
01 04 * * * open -a EyeTV.app /Users/yourname/.shepherd/output.xml
Another possibility would be to use AppleScript, but that probably makes life harder rather than easier.
A full list of command-line options:
~/.shepherd/shepherd --help
The status screen:
~/.shepherd/shepherd --status
What Shepherd's been up to:
~/.shepherd/shepherd --history
Check your channel mappings:
~/.shepherd/shepherd --show-channels
Re-configure Shepherd (preserving old settings except where overridden):
~/.shepherd/shepherd --configure
Check whether any components are missing Perl modules or need to be configured:
~/.shepherd/shepherd --check
Check your config:
~/.shepherd/shepherd --show-config
Shepherd and its components rely on various third-party Perl modules. Some are mandatory, meaning that Shepherd won't run without them. Most, however, are optional, meaning that Shepherd can still operate without them, but some of its components (including grabbers) won't.
You should install all the optional modules if possible, as this increases Shepherd's efficiency, reliability, and possibly the quality of the guide data it delivers. For more information, see [wiki:FAQ#Howimport antisittoinstalltheoptionalPerlmodules the FAQ].
To see which Perl modules you're missing, do this:
~/.shepherd/shepherd --check
If applicable, follow the distribution-specific instructions for [wiki:Installation#DebianBasedDistributions Debian-based], [wiki:Installation#FedoraCore6FC6 Fedora Core 6], and [wiki:Installation#Gentoo Gentoo]. Alternately you can use the [wiki:Installation#NonDistributionSpecific general method].
The following command should install the necessary packages:
sudo apt-get install xmltv libxml-simple-perl libjavascript-perl libalgorithm-diff-perl \
libgetopt-mixed-perl libcompress-zlib-perl libdata-dumper-simple-perl \
libdate-manip-perl liblist-compare-perl libdatetime-format-strptime-perl \
libhtml-parser-perl libxml-dom-perl libgd-gd2-perl libdigest-sha1-perl \
libarchive-zip-perl libio-string-perl libdbi-perl
Xubuntu Jaunty alpha: The Shepherd/MythTV.pm module also needs libclass-dbi-mysql-perl
Ubuntu Lucid 10.04 and later: In Lucid, Ubuntu removed the Perl module JavaScript. Without this, Shepherd will work but may produce da ta of significantly poorer quality.
To enable JavaScript in Ubuntu Lucid 10.04 and later, you must manually install two packages: libmozjs0d and libjavascript-perl.
- Visit http://launchpad.net/ubuntu/lucid/+package/libmozjs0d
- Under "Published Versions" click the link that matches your architecture (amd64, i386, etc).
- Under "Downloadable files" click the link for the .deb package
- Download the .deb file, run it, and click "Install Package." Exit when finished.
- Visit http://launchpad.net/ubuntu/+source/libjavascript-perl/1.14-1
- Under "Builds" click the link that matches your architecture (am64, i386, etc).
- Under "Built Files" click the link for the .deb package
- Download the .deb file, run it, and click "Install Package." Exit when finished.
- (optional) To confirm you have JavaScript support, run tv_grab_au --update''. The grabbers ''rex'' and ''news'' should install with no errors. You may also wish to ''tv_grab_au --check.
Providing you have your yum/smart system setup for ATrpms.net (see http://www.atrpms.net/install.html), all of the required modules can be installed with:
An older version of the perl JavaScript module needs to be installed since the newer versions (after 1.04) do not install properly even with the force option. Just take the default answers to the three questions about SpiderMonkey
sudo yum -y install perl-GD perl-Algorithm-Diff perl-XML-Parser perl-TermReadKey \
js js-devel perl-XML-XQL perl-IO-String perl-XML-Simple perl-DateTime-Format-Builder \
perl-List-Compare perl-DateTime-Format-Strptime tor xmltv
cd /tmp
wget http://ftp.mozilla.org/pub/mozilla.org/js/js-1.60.tar.gz
tar xvzf js-1.60.tar.gz
cd js/src
make -f Makefile.ref BUILD_OPT=1
cp jsopcode.tbl /usr/include
cpan -f C/CL/CLAESJAC/JavaScript-1.04.tar.gz
The process is very similar to that of the Fedora Core 6:
su
yum -y install perl-GD perl-Algorithm-Diff perl-XML-Parser perl-TermReadKey \
js js-devel perl-XML-XQL perl-IO-String perl-XML-Simple perl-DateTime-Format-Builder \
perl-List-Compare perl-DateTime-Format-Strptime tor xmltv gcc
Digest::SHA1 does not come with Mythdora 4 so you will need to install it with cpan. The first time you run cpan you will be asked to configure it, the default options should be fine.
cpan Digest::SHA1
On Mythdora 5 Digest::SHA1 can be installed as an rpm.
yum install perl-Digest-SHA1 -y
An older version of the perl JavaScript module needs to be installed since the newer versions (after 1.04) do not install properly even with the force option. Just take the default answers to the three questions about SpiderMonkey
cd /tmp
wget http://ftp.mozilla.org/pub/mozilla.org/js/js-1.60.tar.gz
tar xvzf js-1.60.tar.gz
cd js/src
make -f Makefile.ref BUILD_OPT=1
cp jsopcode.tbl /usr/include
cpan -f C/CL/CLAESJAC/JavaScript-1.04.tar.gz
On Mythdora 10.21 the only addition to the above guide is the requirement of perl-Crypt-SSLeay and perl-CPAN which can be installed via yum
yum install -y perl-Crypt-SSLeay perl-CPAN
You may also have to install cpan before using it to install Digest::SHA1,
yum install cpan
On Mythdora 12.23 (based on Fedora 12) you must be very careful to answer Yes to the "Is your SpiderMonkey compiled with JS_THREADSAFE" question, or JavaScript will not install properly. All other questions can be anwered with the defaults.
sudo yum -y install perl-GD perl-Algorithm-Diff js js-devel perl-XML-XQL \
perl-DateTime-Format-Builder perl-List-Compare perl-DateTime-Format-Strptime \
tor gcc perl-Digest-SHA1 perl-Digest-SHA perl-Crypt-SSLeay perl-CPAN
sudo cpan YAML
sudo cpan JavaScript
Same as Mythdora 12.23 you must be very careful to answer Yes to the "Is your SpiderMonkey compiled with JS_THREADSAFE" question, or JavaScript will not install properly. All other questions can be anwered with t he defaults.
sudo yum -y install perl-GD perl-Algorithm-Diff js js-devel perl-XML-XQL \
perl-DateTime-Format-Builder perl-List-Compare perl-DateTime-Format-Strptime \
tor gcc perl-Digest-SHA1 perl-Digest-SHA perl-Crypt-SSLeay perl-CPAN \
perl-YAML
sudo cpan JavaScript
Some (but not all) of the mandatory modules can be installed with:
sudo emerge -av xmltv Algorithm-Diff Digest-SHA1 dev-perl/HTTP-Cache-Transparent dev-perl/JavaScript-SpiderMonkey dev-perl/XML-DOM
For the rest, you can use g-cpan (e.g. "sudo g-cpan -i List::Compare"). You may wish to useeix to search for new ebuil ds before installing (e.g. "eix -s List::Compare").
Alternately, you can use the [wiki:Installation#NonDistributionSpecific non-distribution specific method].
DO NOT USE CPAN to install your dependancies. you are on freebsd now - use the ports...
You should have perl installed as you have probably spent several hours trying to make it work but just in case you dont...
cd /usr/ports/lang/perl5.8
make install
now to get shepherd basics working
cd /usr/ports/textproc/p5-xmltv
make install
cd /usr/ports/devel/p5-Algorithm-Diff
make install
cd /usr/ports/misc/p5-List-Compare
make install
NB: JavaScript and SpiderMonkey
cd /usr/ports/lang/p5-JavaScript-SpiderMonkey
make install
this should add all REQUIRED modules for you as well as the optional module for spidermonkey
from here you should now be able to type perl shepherd and have shephard tell you where it is about to install
you will still need to install modules such as
XML/DOM.pm aka XML::DOM aka /usr/ports/textproc/p5-XML-DOM
DBI.pm /usr/ports/databases/p5-DBI
or
JavaScript.pm aka /usr/ports/lang/p5-JavaScript
there may be others depending on your install
look these up as freebsd ports, again, do not use cpan
NB: freeBSD section added 26 September 2008
Starting with a minimal x86_64 or i586 Mandriva 2010.0 installation, the following will install all the Shepherd dependencies.
urpmi --auto libjs1 perl-Algorithm-Diff perl-Compress-Raw-Zlib perl-Crypt-SSLeay \
perl-DBD-mysql perl-Digest-SHA1 perl-HTML-Tree perl-HTTP-Cache-Transparent \
perl-JavaScript perl-List-Compare perl-XML-DOM perl-XML-Simple wget xmltv
Its simple, Shepherd is in the repo already so its just a matter of issuing the following command and you should be good to go
pacman -S shepherd
Easy Hey!
After the initial install of the system, you need certain perl dependencies to build xmltv:
cpan Term::ReadKey Date::Manip File::Slurp XML::Writer
Then build and install xmltv manually as described below.
Then install the remaining mandatory and optional perl dependencies as described in 'Non-Distribution Specific'.
The general method to install Perl modules is to do this (as root):
cpan <module>
For example:
cpan List::Compare
This will install the mandatory Perl modules:
cpan XMLTV::Ask Algorithm::Diff Compress::Zlib Cwd Data::Dumper Date::Manip Getopt::Long \
List::Compare LWP::UserAgent POSIX Digest::SHA1
And this will install the optional ones:
cpan DateTime::Format::Strptime File::Basename File::Path GD HTML::Entities \
HTML::TokeParser HTML::TreeBuilder IO::File Storable Time::HiRes XML::DOM \
XML::DOM::NodeList XML::Simple Storable HTTP::Cookies File::Basename \
LWP::ConnCache GD Digest::MD5 Archive::Zip IO::String \
DateTime::Format::Strptime JavaScript
(Note: this list may not be up to date. If Shepherd complains about more missing modules, install those with cpan as described above.)
It's safe to run these commands even if you have some modules installed; it will leave any previously-installed modules alone, so long as they're the most recent versions.
XMLTV can also be downloaded from http://files.xmltv.org/.
If you are unsure about whether you have XMLTV installed, run the command perldoc XMLTV and see if there is any documentation on your system. If there is, then it is already installed.
XMLTV version 0.5.44 or later is recommended as it supports HDTV flags.
The JavaScript module enables grabbers to read web pages with embedded Javascript. It can be a difficult module to install on some distributions, but provides access to significantly better quality TV guide data.
RedHat Fedora: If you're running a RedHat Fedora system, you can verify whether you have the required JavaScript perl module bindings js'' and ''js-devel through RPM:
# rpm -q js js-devel
js-1.5-2.fc3
js-devel-1.5-2.fc3
Providing rpm responds with something similar to above, the javascript library files are installed and you can proceed with installing the perl javascript bindings. If rpm indicates the packages are not installed, you will need to install them from a RPM repository. [rpmfind.net] can be useful here:
- http://rpmfind.net/linux/rpm2html/search.php?query=js-devel
- http://rpmfind.net/linux/rpm2html/search.php?query=js
!Gentoo First emerge the supporting libraries:
emerge dev-perl/JavaScript-SpiderMonkey
then install the Javascript perl bindings from CPAN:
perl -MCPAN -e 'install JavaScript'
Some grabbers work faster/better if they can operate using The Onion Router (tor) from http://tor.eff.org/. Once Tor is installed, shepherd will automatically find it and start using it. No configuration of Tor i s necessary.
Tor is available in RPM form from as http://tor.eff.org/dist/rpm/tor-0.1.1.25-tor.0.rh4_4.i386.rpm and http://dag.wieers.com/packages/libevent/libevent-1.2-1.fc3.rf.i386.rpm
For Debian-based installations, a simple "sudo apt-get install tor" will get things working.
Shepherd automatically checks for new versions of itself and its components, downloads, and executes them. See [wiki:Security] for details and implications.
It is possible to use a single installation of Shepherd to grab data for multiple sources (such as FTA & Foxtel in the following example).
You can do this by using the following steps:
-
Using mythtv-setup create two channel sources, one for FTA and another for Foxtel.
-
Select tv_grab_au as the grabber for both of these sources
-
Add cards and channels to the appropriate sources as required
-
Configure shepherd to grab data for both the FTA and Foxtel channels that you have configured in Myth
-
From a frontend, select setup -> general. On the last page you can schedule mythfilldatabase to be run automatically. This page also allows you to add parameters to the mythfilldatabase command line, to which you must add '--update'. This prevents Myth from adding the Foxtel channels to the FTA source, and vice-versa.
Whilst Mythfilldatabase will call Shepherd twice (once for each source), data will only be downloaded once for both FTA and Foxtel during the first run, as Shepherd will automatically use cached data when run twi ce in a short period of time.
For further information, please see [wiki:FAQ the FAQ].
JavaScript with Suse 11.0 The reason Javascript won't build is because the libjs .h files are in the wrong directory. A simple way of addressing this build issue is to temporarily add a symlink:
cd /usr/include
ln -s js smjs
cpan JavaScript
rm smjs
JavaScript with Suse 10.1, 10.2 and 10.3 After installing libjs and libjs-devel you will still be missing some files to get 'cpan JavaScript' working please be careful with the following it is more of a hack than a fix.
wget http://ftp.mozilla.org/pub/mozilla.org/js/js-1.60.tar.gz
tar zxvf js-1.60.tar.gz
cd js/src
make -f Makefile.ref BUILD_OPT=1
cp js*.h /usr/include/
cp jsopcode.tbl /usr/include/
cd Linux_All_OPT.OBJ
cp js*.h /usr/include/
cp libjs.* /usr/include/
ldconfig
‘cpan JavaScript’ will still have issues but should be about 86% successful, you can now do a force install by
pc:/ # cpan
cpan> force install JavaScript
If the compile complains about missing include files, but they exist on your system in a different directory tree, maybe link the trees: [in my case, one of the directories in the "-I" include-file search path was a non-existant /usr/lib/MozillaFirefox, but they exist under /usr/lib/mozilla-firefox]
cd /usr/lib
ln -s mozilla-firefox MozillaFirefox
This will cause the files to be found under both the 'real' path, and the path that JavaScript thinks they should be, and a re-attempt to install JavaScript worked OK.