diff options
Diffstat (limited to 'abs/core/local-website/htdocs/mythtv-doc/mythtv-HOWTO.sgml')
| -rw-r--r-- | abs/core/local-website/htdocs/mythtv-doc/mythtv-HOWTO.sgml | 7977 |
1 files changed, 7977 insertions, 0 deletions
diff --git a/abs/core/local-website/htdocs/mythtv-doc/mythtv-HOWTO.sgml b/abs/core/local-website/htdocs/mythtv-doc/mythtv-HOWTO.sgml new file mode 100644 index 0000000..08fc851 --- /dev/null +++ b/abs/core/local-website/htdocs/mythtv-doc/mythtv-HOWTO.sgml @@ -0,0 +1,7977 @@ +<!doctype linuxdoc system> +<article> +<title>Installing and using MythTV +<author>Robert Kulagowski, <url url="mailto:rkulagow@rocketmail.com" +name="mailto:rkulagow@rocketmail.com"> +<date>2008-06-04, v0.21.02 +<abstract> +Initially, installation of MythTV seems like a huge task. There are lots +of dependencies, and various distributions seem to do the same thing +different ways. This document will attempt to give general installation +instructions, as well as including distribution-specific instructions where +necessary. +</abstract> +<toc> +<sect>First things first. +<p><figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +<bf>NOTE</bf>: Please note that I, Robert Kulagowski, am <em>NOT</em> the +author/programmer of the MythTV application! I can not give you +personalized installation support. If you are having issues installing +MythTV you should examine the archives, or post your question to the +MythTV-users mailing list. If you send me "Does MythTV work with 'X'"? +messages - I will simply instruct you to ask your question on the +mythtv-users mailing list. +</caption> +</figure> +<sect1>What is MythTV? +<p>MythTV is a GPL licensed suite of programs that allow you to build the +mythical home media convergence box on your own using Open Source software +and operating systems. MythTV is known to work on Linux and Mac OS X +(PowerPC and Intel). It does not run on Windows. + +MythTV has a number of capabilities. The television portion allows you to +do the following: +<itemize> +<item>You may pause, fast-forward and rewind live Television. +<item>You may install multiple video capture cards to record more than one +program at a time. +<item>You can have multiple servers (called "backends"), each with multiple +capture cards in them. All scheduling is performed by the Master backend, +which arbitrates which recording will be performed by each device. All +recording requests are managed by the Master backend, so you can schedule a +recording from any client. +<item>You can have multiple clients (called "frontends" in MythTV parlance), +each with a common view of all available programs. Any client can watch any +program that was recorded by any of the servers, assuming that they have the +hardware capabilities to view the content; a low-powered frontend will not +be able to watch HDTV, for example. Clients can be diskless and controlled +entirely by a remote control. +<item>You may use any combination of standard analog capture card, MPEG-2, +MJPEG, DVB, HDTV, USB and firewire capture devices. With appropriate +hardware, MythTV can control set top boxes, often found in digital cable and +satellite TV systems. +<item>Program Guide Data in North America is downloaded from +schedulesdirect.org, a non-profit organization which has licensed data from +Tribune Media Services. This service provides almost two weeks of +scheduling information. Program Guide Data in other countries is obtained +using XMLTV. MythTV uses this information to create a schedule that +maximizes the number of programs that can be recorded if you don't have +enough tuners. +<item>MythTV implements a UPNP server, so a UPNP client should automatically +see content from your MythTV system. +</itemize> +Other modules in MythTV include: +<itemize> +<item>MythArchive, a tool to create DVDs +<item>MythBrowser, a web browser +<item>MythControls, an application to configure your remote control +<item>MythFlix, a Netflix module +<item>MythGallery, a picture-viewing application +<item>MythGame +<item>MythMusic, a music playing / ripping application which supports MP3 +and FLAC +<item>MythNews, a RSS news grabber +<item>MythPhone, phone and videophone using SIP. +<item>MythVideo, DVD ripper and a media-viewer for content not created within MythTV +<item>MythWeather +<item>MythWeb, which allows you to control your MythTV system using a web +browser. With MythWeb, you can schedule and delete recordings, change +keybindings and more. With proper security, you may even schedule a program +over the Internet and have it immediately acted on by the Master backend. +</itemize> +<sect1>QuickStart +<p>Custom mini-distributions are available to make it easier to install +MythTV. A mini-distribution removes many of the "general purpose" +workstation / server software packages that may be installed by default if +you use one of the big-name OS packages. + +See <url url="http://mysettopbox.tv" name="http://mysettopbox.tv"> if you'd +like to install a custom version of Knoppix optimized for MythTV. + +See <url url="http://www.minimyth.org" name="http://www.minimyth.org"> if you'd like +to install MythTV onto a diskless system. + +See <url url="http://bit.blkbk.com" name="http://bit.blkbk.com"> if you'd +like to install MythTV on a Xbox. +<bf>NOTE</bf>: Site appears unmaintained. + +See <url url="http://wilsonet.com/mythtv/" +name="http://wilsonet.com/mythtv/"> for instructions tailored to RedHat's +Fedora Core distribution. + +See <url url="http://www.mythbuntu.org" name="http://www.mythbuntu.org"> if +you'd like to install a customized version of Ubuntu optimized for MythTV. + +There is a MythTV wiki at <url url="http://wiki.mythtv.org" +name="http://wiki.mythtv.org">. + +If you are installing this version for Schedules Direct support, please see +the <ref id="migratingtoSD" name="Migrating from DataDirect Labs to +Schedules Direct"> section for additional information. + +<sect1>Upgrading from previous versions +<p>The upgrade from previous versions should be transparent. Any changes to +the database structure should be applied automatically. + +It is <em>strongly</em> recommended that you back up your database before +installing a new version of MythTV. + +See <ref id="backupdb" name="Saving or Restoring the database"> for instructions. + +<sect1>How to obtain this document / PDF versions of this document <label id="how_to_obtain"> +<p>This HOWTO document is maintained at the primary MythTV website: <url +url="http://www.mythtv.org" name="http://www.mythtv.org"> by Robert +Kulagowski <url url="mailto:rkulagow@rocketmail.com">. + +This document is available as a single-page HTML document at <url +url="http://www.mythtv.org/docs/mythtv-HOWTO-singlehtml.html" +name="http://www.mythtv.org/docs/mythtv-HOWTO-singlehtml.html"> or as a PDF +at <url url="http://www.mythtv.org/docs/mythtv-HOWTO.pdf" +name="http://www.mythtv.org/docs/mythtv-HOWTO.pdf">. + +This HOWTO is for MythTV v0.21 + +Release notes for this version may be found in the MythTV Wiki at <url +url="http://www.mythtv.org/wiki/index.php/Release_Notes_-_0.21" +name="http://www.mythtv.org/wiki/index.php/Release_Notes_-_0.21"> + +<sect1>Books about MythTV +<p>If you would like to purchase a book specifically about MythTV: + +<itemize> +<item>Hacking MythTV, ISBN 978-0470037874 by Wilson, Tittel, Wright and Korelc +<item>Practical MythTV: Building a PVR and Media Center PC, ISBN 978-1590597798 by Smith and Still +</itemize> + +<sect1>Document conventions +<p>The following conventions are used throughout this document.<newline> +<bf>boldface</bf> - used for program names.<newline> +<tt>typewriter</tt> - used for program paths.<newline> +<em>emphasis</em> - Pay attention here.<newline> + +<figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption> +Pay more attention. +</caption> +</figure> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +Ignore at your own peril. +</caption> +</figure> + +<figure loc="here"> +<eps file="add.eps" height="1cm"> +<img src="add.png"> +<caption> +Feature that has been added to SVN (subversion, a revision control system) +but is not available in the current release. +</caption> +</figure> + +<sect1>Mailing lists / getting help +<p>It's recommended that you join the user list at <url +url="http://www.mythtv.org/mailman/listinfo/mythtv-users" +name="http://www.mythtv.org/mailman/listinfo/mythtv-users">. The developer +list is at <url url="http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev" +name="http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev">. Please keep +the developer list strictly for development-related issues. + +Searchable archives for the lists are available at <url +url="http://www.gossamer-threads.com/lists/mythtv/" +name="http://www.gossamer-threads.com/lists/mythtv/">. + +<sect1>IRC +<p>There are two IRC channels dedicated to MythTV which can be found on +irc.freenode.net +<itemize> +<item>mythtv +<item>mythtv-users +</itemize> + +The <tt>mythtv</tt> channel is where the developers discuss code. It is +<em>not</em> a user-support channel. Please don't ask non-development +related questions there. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +Really. Even if there's no one in the mythtv-users IRC group or everyone +seems to be ignoring you. +</caption> +</figure> + +<sect1>Bug database +<p>If you feel you need to contribute to a bug database, use the MythTV bug +ticketing system at <url url="http://svn.mythtv.org/trac" +name="http://svn.mythtv.org/trac">. + +Good entries will contain the following: +<enum> +<item>Qt version +<item>Linux distribution +<item>gcc version +<item>the last entry in config.log to detail how you compiled +<item>MythTV version numbers (<em>e.g.</em>from mythfrontend --version) +<item>Hardware +<item>How you are able to reproduce the bug +</enum> + +See the instructions on how to debug in <ref id="debugging" name="Section 22">. + +The bug database is not a chat room, so restrict your entries to what is +relevant. It's also not a repository of feature requests; a feature request +without an accompanying patch file to implement that feature will be quickly +closed. There is a feature wishlist on the wiki at <url +url="http://www.mythtv.org/wiki/index.php/Feature_Wishlist" +name="http://www.mythtv.org/wiki/index.php/Feature_Wishlist">. There is no +guarantee that anything on the wishlist will ever get code written to +implement it. + +If a developer closes out your bug, it's likely you didn't provide enough +information. Don't re-open a bug without providing additional information. + +<sect1>Contributing to this document +<p>Contributions to the HOWTO are welcome, especially if you find a +grammatical or spelling error, or if the wording of something is just plain +confusing. + +If you'd like to make a new contribution, create a ticket at <url +url="http://svn.mythtv.org/trac" name="http://svn.mythtv.org/trac"> and +click "New Ticket". The type should be set to "patch" and the owner set to +"rkulagow" to ensure that I see your contribution. + +Please send it as either SGML or as plain text. <em>NO HTML</em>. The +source used to create the HOWTO is in SGML / Linuxdoc. Do not be afraid of +SGML! A quick look at the source of this HOWTO will show that it is not +difficult, because there aren't that many tags to worry about, so at least +<em>try</em> to submit as SGML. See the Linuxdoc HOWTO at <url +url="http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html" +name="http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html"> for information +on the linuxdoc format itself, or look at the <tt>mythtv-HOWTO.sgml</tt> +file as an example. + +To create the actual patch, run <bf>diff -u origfilename newfile > +doc.patch</bf> and attach your contribution to the trac ticket. + +<sect>Introduction. +<p>This HOWTO document will focus on manually building MythTV in a North +American environment. If you have installation instructions for a different +region or Linux distribution, please send them to the author so that it can +be included in other versions of this document. + +<sect>Checking prerequisites. +<p>You must ensure that any firewalls (either hardware, or a software +firewall installed by your distribution) will not block access to the ports +that will be used by the MythTV clients and servers on the "inside" LAN. +The ports for MySQL (TCP port 3306) and mythbackend (TCP ports 6543 and +6544) must be open. It is <em>strongly</em> recommended that you do +<em>not</em> expose the MythTV and MySQL ports to the Internet or your +"Outside" LAN. + +<sect1>Hardware +<p>Hardware selection is a complex topic, one this HOWTO will only discuss +briefly and in general terms. The following subsections offer some general +guidance but stop short of offering specific recommendations. + +For a good MythTV experience, you must understand that MythTV exercises your +hardware more than a typical desktop. Encoder cards generate DMA across the +PCI bus. The CPU is busy encoding / decoding video. Hard drives are +constantly reading and writing data. Building a MythTV system on older / +"spare" hardware may be an exercise in frustration and can waste many hours +of valuable time. + +For more detail about actual configurations that others have used, Mark +Cooper has setup a hardware database at <url +url="http://pvrhw.goldfish.org/" name="http://pvrhw.goldfish.org/">. The +website will let you browse what other users have reported as their hardware +configuration, and how happy they are with the results. + +If you have specific questions about the suitability of specific hardware +choices, you can consult the archives of the mythtv-users mailing list at +<url url="http://www.gossamer-threads.com/lists/mythtv/" +name="http://www.gossamer-threads.com/lists/mythtv/"> or +post a question to the list. +<sect2>CPU Type and Speed +<p>Selection of CPU type and speed is one of the trickiest elements of +hardware selection, mainly because there are so many tradeoffs which can be +made. For example, if you have plenty of CPU, you can use higher bitrates +or capture sizes, etc. + +MythTV has two modes of operation. First, it can function as a software +video encoder, which means that it uses a fairly generic "dumb" video +capture card to get frames of video, encodes them using the CPU on your +motherboard and writes them to disk. High-end video capture cards and +devices like the TiVo and ReplayTV have dedicated encoder chips which use +specialized hardware to convert the video stream to the MPEG-2 format +without using the motherboard CPU. The main CPU has the responsibility of +running the Operating System and reading and writing the encoded frames to +the disk. These tasks have fairly low CPU requirements compared to encoding +video, which is why a device like a Series 1 TiVo can run with only 16MB of +RAM and a 54MHz CPU. + +There are many variables that go into the question: "How fast a CPU do I +need to run MythTV"? Obviously, the faster your CPU, the better your +experience will be with MythTV. If you are using the software MPEG-4 +encoder and performing the "Watch TV" function, where the CPU is both +encoding and decoding video simultaneously to allow Pause, Fast Forward and +Rewind functions for live TV requires more CPU then just encoding or +decoding. MythTV also supports multiple encoder cards in a single PC, +thereby increasing the CPU requirements if you plan on simultaneously +encoding multiple programs. As a general guideline, plan on 1GHz per +encoder if you are doing software-based encoding, less if you are using a +hardware-based encoder. + +Here are a few data points: +<itemize> +<item>A PIII/733MHz system can encode one video stream using the MPEG-4 +codec using 480x480 capture resolution. This does not allow for live TV +watching, but does allow for encoding video and then watching it later. +<item>A developer states that his AMD1800+ system can <bf>almost</bf> +encode two MPEG-4 video streams and watch one program simultaneously. +<item>A PIII/800MHz system with 512MB RAM can encode one video +stream using the RTjpeg codec with 480x480 capture resolution and play it back +simultaneously, thereby allowing live TV watching. +<item>A dual Celeron/450MHz is able to view a 480x480 MPEG-4/3300kbps file +created on a different system with 30% CPU usage. +<item>A P4 2.4GHz machine can encode two 3300Kbps 480x480 MPEG-4 files and +simultaneously serve content to a remote frontend. +</itemize> + +The second mode of operation is where MythTV is paired with a hardware-based +video encoder, such as a Matrox G200 or a Hauppauge +WinTV-PVR-150/250/350/500. In this mode, because the video encoding is +being done by a dedicated video processor, the host CPU requirements are +quite low. See the <ref id="video_capture_device" name="Video Capture +Device"> section for details. + +The price differential between a frame grabber and a card that implements +hardware MPEG-2 encoding, such as the Hauppauge PVR-x50 series, is now less +than $30 US. Primary development in MythTV has transitioned to supporting +MPEG-2 capture devices and HDTV, so if given the option, go with the +hardware MPEG-2 encoder. + +If you have a Via M10000 series or a Hauppauge PVR-350, MythTV can use the +hardware-based video decoder for playback, which further reduces CPU +requirements. + +<sect2>Memory +<p>A MythTV host that is both a backend and a frontend and using software +encoding with a single capture card should run adequately in 256MB of RAM. +Additional RAM above 256MB will not necessarily increase performance, but +may be useful if you are running multiple encoders. + +<sect2>Hard Disk(s) +<p>Encoded video takes up a lot of hard disk space. The exact amount depends +on the encoding scheme, the size of the raw images and the frames per +second, but typical values for MythTV range from 700 megabytes/hour for +MPEG-4, 2 GB/hour for MPEG-2 and RTjpeg and 7 GB/hour for ATSC HDTV. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: You <em>must</em> use DMA for hard drive access to prevent +choppy or jittery video. Not all distributions enable DMA at boot time. +See the Troubleshooting Section for <ref id="Setting_DMA" +name="instructions"> on how to do this.</caption> +</figure> + +Writing video to disk is sensitive to timing issues; RTjpeg requires less +CPU with the tradeoff being larger files and needing to write to the disk +faster. MPEG-4 requires more CPU, but the files are smaller. At the +default resolution, MPEG-2 creates the largest files of all with almost no +CPU impact. + +See the Troubleshooting <ref id="Setting_DMA" name="section"> for more +information. + +<sect2>Filesystems +<p>MythTV creates large files, many in excess of 4GB. You <em>must</em> +use a 64 or 128 bit filesystem. These will allow you to create large files. +Filesystems known to have problems with large files are FAT (all versions), +and ReiserFS (versions 3 and 4). + +Because MythTV creates very large files, a filesystem that does well at +deleting large files is important. Numerous benchmarks show that XFS and +JFS do very well at this task. You are <em>strongly</em> encouraged to +consider one of these for your MythTV filesystem. JFS is the absolute best +at deletion, so you may want to try it if XFS gives you problems. MythTV +.21 incorporates a "slow delete" feature, which progressively shrinks +the file rather than attempting to delete it all at once, so if you're more +comfortable with a filesystem such as ext3 (whose delete performance for +large files isn't that good) you may use it rather than one of the +known-good high-performance file systems. There are other ramifications to +using XFS and JFS - neither offer the opportunity to shrink a filesystem; +they may only be expanded. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: You <em>must not</em> use ReiserFS v3 for +your recordings. You will get corrupted recordings if you do. +</caption> +</figure> + +Because of the size of the MythTV files, it may be useful to plan for future +expansion right from the beginning. If your case and power supply have the +capacity for additional hard drives, read through the <ref id="LVM" +name="LVM"> and <ref id="advancedpartitionformatting" name="Advanced +Partition Formatting"> sections for some pointers. + +<label id="video_capture_device"> +<sect2>Video Capture Device +<p>In order to capture video, MythTV will need one or more video capture +devices with Linux drivers. There are a number of classes of hardware +available for capturing video. +<sect3>Frame Grabbers. +<p>This class of card is the simplest and is usually the cheapest. There is no +on-board encoding of the analog video; hardware known as a Digital-Analog +Converter (DAC) takes the video and presents it to the computer in an +essentially raw digital form. + +For a list of video capture cards known to work with Linux, please see +<tt>/usr/src/linux/Documentation/video4linux/bttv</tt> for a partial +listing; even if your specific card is not listed, it may be that the vendor +is actually using a standard reference design and placing their own name on +it. See the video4linux mailing list (<url +url="https://listman.redhat.com/mailman/listinfo/video4linux-list" +name="https://listman.redhat.com/mailman/listinfo/video4linux-list">) for +more information and for specific hardware questions. + +The most common inexpensive cards available use the Bt848, Bt878 or CX2388x +series of video capture chips; examples are the "Hauppauge WinTV Go" card and +the "AverTV Desktop PVR" card, both of which use the bttv kernel module. + +<code> +NOTE: The ATI TV Wonder series and the ATI All-in-Wonder series of cards +are not the same. The All-in-Wonder cards will not work with MythTV. +</code> + +<figure loc="here"> +<eps file="stop.eps" height="4cm"> +<img src="stop.png"> +</figure> +<figure loc="here"> +<eps file="stop.eps" height="4cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: The ATI All-in-Wonder cards (which are not the same +as the ATI TV Wonder, TV Wonder VE or TV Wonder Pro) <em>will not</em> work +as a MythTV capture device because the GATOS <url +url="http://gatos.sourceforge.net" name="http://gatos.sourceforge.net"> +drivers that are available provide only a limited subset of the V4L API. +The TV Wonder series of cards are supported by the Bt8x8 Video4Linux driver. +</caption> +</figure> + +After you have installed a suitable capture device, you can check that +the kernel sees it with <tt>lspci</tt>. Look for an entry labeled "Multimedia +video controller". To get more detailed information about the card, use +<tt>lspci -v</tt> or <tt>lspci -vv</tt>. Ensure that your system is loading +the bttv modules by typing: +<tscreen><verb> +# lsmod |grep bttv +</verb></tscreen> + +You want to see the <tt>bttv</tt> module listed. +<sect3>Hardware MPEG-2 encoders. +<p>While inexpensive video-capture cards simply capture raw frames, leaving +encoding to software, some higher-end cards incorporate hardware-based +encoding. Using either a G200 MJPEG encoder card, or a MPEG-2 encoder card +supported by the IvyTV project <url url="http://ivtvdriver.org/" +name="http://ivtvdriver.org"> such as the Hauppauge +PVR-150/250/350/500, Avermedia M179, Hauppauge "Freestyle" or Yuan M600 +cards will allow you to use dedicated hardware encoders rather than your +CPU. (The PVR-350 can simultaneously be used as an output device.) Using the +on-board MPEG-2 encoder greatly reduces the CPU requirements for +encoding. + +The ivtv driver was incorporated into the Linux kernel starting at v2.6.22. + +There is a Beta driver for the HVR-1600 card at <url +url="http://www.ivtvdriver.org/index.php/Cx18" +name="http://www.ivtvdriver.org/index.php/Cx18"> + +<bf>NOTE</bf>: Motherboards with the Via chipset are notoriously bad with +DMA and have caused numerous issues with ivtv, including hard locks. See +the ivtv website <url url="http://ivtvdriver.org" name="http://ivtvdriver.org"> +for the latest information on what works and what doesn't. + +Here are some data points for encoding: +<itemize> +<item>A Celeron 450 uses 2% CPU for encoding a 480x480 16Mbps MPEG-2 stream. +</itemize> + +Here are some data points for decoding: + +<itemize> +<item>An Athlon 1800XP can decode a 720x480 8Mbps MPEG-2 file using 10% CPU +<item>An Athlon 1GHz can decode a 720x480 16Mbps MPEG-2 file using 30-50% +CPU, can decode a 480x480 16Mbps MPEG-2 using 30% CPU and approximately 30% +for Live TV at 416x480. +<item>A P3-550 can decode a 480x480 16Mbps MPEG-2 file with 55% CPU. +<item>A Celeron 450 (no SSE) can decode a 480x480 16Mbps MPEG-2 file with +80% CPU. +</itemize> + +<sect3>DVB capture cards. +<p>DVB is a video standard primarily found in Europe (where it comes in +DVB-C, DVB-T and DVB-S varieties for Cable, Terrestrial and Satellite) and +is also used as the programming interface for HDTV capture cards in Linux. +To see if your DVB card is supported, see the list of cards in the +"Supported Hardware" section of the DVB Wiki at <url +url="http://www.linuxtv.org/wiki/index.php/Main_Page" +name="http://www.linuxtv.org/wiki/index.php/Main_Page"> for more +information. + +In the United States, you may use a card such as the TwinHan to obtain +unencrypted Free-To-Air satellite channels. See <url +url="http://www.lyngsat.com/" name="http://www.lyngsat.com/"> for the types +of content which is available. + +<sect3>HDTV. +<p>There are a number of HDTV cards with Linux drivers which are known to +operate in the United States; a complete list of cards with DVB drivers can +be found at <url url="http://www.linuxtv.org/wiki/index.php/ATSC_Devices" +name="http://www.linuxtv.org/wiki/index.php/ATSC_Devices"> Some cards +support capture of unencrypted digital cable TV (utilizing QAM256), others +will only work with Over The Air (aka "OTA") signals captured with an +antenna (with 8VSB). + +Cards that have been reported to work include: +<itemize> +<item>pcHDTV HD-2000, Air2PC PCI rev 1-3 (8VSB only) +<item>SiliconDust HDHomeRun (8VSB, QAM256) +<item>pcHDTV HD-3000/5500 (8VSB, QAM256) +<item>Air2PC HD-5000 (8VSB, QAM256) +<item>DViCO Fusion HDTV Lite/Gold 5 (8VSB, QAM256) +</itemize> + +<bf>NOTE</bf>: There are no known consumer-level capture devices which will +allow you to capture the HDTV output (DVI, HDMI, VGA, YPbPr / Component) +from a set-top box commonly found with digital cable systems or satellite +systems. <em>None</em> of the capture devices listed above +perform any encoding; they merely allow your computer to save a copy of a +HDTV stream which has already been converted to MPEG-2 at the broadcast +facility. + +<bf>NOTE:</bf>: All of the cards listed above (except for the HD-2000 and +HDHomeRun) should be configured as DVB cards. The HD-2000 can be configured +as a pcHDTV card if you use the V4L drivers from <url +url="http://www.pchdtv.com" name="http://www.pchdtv.com"> and use Linux +kernel 2.6.9 or earlier. With kernel 2.6.10 and higher it must be +configured as a DVB card, but you lose access to the second antenna input in +ATSC mode. The HDHomeRun should be configured as two HDHomeRun cards, one +for each tuner. + +To playback HDTV content, plan on a powerful CPU. "How powerful?" depends +on a number of factors, such as the capture resolution, whether the video is +progressive or interlaced, and whether your display card has hardware-assist +support for Linux. + +The Simple Answer: Once you are in the 3.2 Ghz P4-class of CPU you should have +no issues with viewing HDTV. + +The Complicated Answer: + +For 720p content (1280x720), a 2.4GHz P4 should be sufficient. + +For 1920x1080i->1920x1080p with the better deinterlacing methods +done in real time a 2.4GHz CPU is taxed, but should work if you use "Bob and +Weave" deinterlacing, or if you have an NVIDIA card with MPEG-2 hardware +acceleration. If you enable the hardware acceleration, you may be able to +use a 1.8GHz processor. + +<sect3>Firewire. +<p>You may use the Firewire output of the Motorola DCT6200 or the SA3250. +If your provider uses 5C encryption on a particular channel, you won't be +able to get any content. + +<sect3>DBoxII or other devices running Neutrino +<p>You may use the Ethernet port of an DBoxII or a similar device to capture +MPEG2. Your set top box has to be running the Neutrino GUI. + +<sect3>USB Capture Devices. +<p>The Plextor ConvertX PVR devices are supported through Linux drivers +available from <url +url="http://www.plextor.com/english/support/LinuxSDK.htm" +name="http://www.plextor.com/english/support/LinuxSDK.htm">. MythTV uses the +Plextor to capture hardware encoded MPEG-4, so the host CPU requirements are low. + +Hauppauge WinTV-PVR-USB2 (driver available at <url +url="http://www.isely.net/pvrusb2/" name="http://www.isely.net/pvrusb2/">) +emulates a PVR-x50 card. + +<sect3>IP Recorder (RTSP, RTS, UDP) +<p>MPEG-2, MPEG-4 and H.264 internet TS stream recording is supported using +the IPTV recorder in MythTV. This recorder expects the channels to be supplied +as a m3u playlist. If your DSL/Fiber provider supplies television service, +but does not provide a m3u playlist for the channels, you can construct one +for your own use. You do not need to download it from the same server as the +streams themselves, and can also read it from a file if this is more convenient. + +<bf>NOTE</bf>: Some DSL providers only allow you to use one recorder at a +time, so you may need to limit yourself to one recorder in MythTV and turn +off any set top box the cable provider sold or rented to you with your +service. This limitation is independent of the bandwidth you have purchased. + +<sect2>Hardware known NOT to work and other issues +<p> +<itemize> +<item>Hauppauge WinTV-D or -HD (no driver) +<item>Hauppauge WinTV-USB series +<item>Hauppauge WinTV-PVR-usb (model 602), or WinTV-PVR-PCI (model 880) cards (no driver - this is not the PVR-250/350 +series of cards supported by the IvyTV driver) +<item>ATI All-in-Wonder series +</itemize> + +<sect2>Sound card +<p>The system needs a sound card or an on-board equivalent on the motherboard +to play back and in most cases, to record sound. Any sound card that can be +operated by the ALSA (Advanced Linux Sound Architecture) kernel modules will +work with MythTV. However, some cards and drivers will provide better +quality or compatibility than others. In particular, many audio +devices included on motherboards can be problematic. + +The usual practice for capturing the audio associated with the video is to +run a cable from an audio output on the video capture card to the Line input +on a sound card. However, some video capture cards provide on-board audio +capabilities that work with the kernel <tt>btaudio</tt> module instead, +thereby eliminating the need for a cable. This is useful if you will be +using multiple capture cards in a single chassis, since each capture card +will not need its own sound card. Note that a separate sound card is still +required for playback when using <tt>btaudio</tt>, and that often the audio +recorded in this way will be mono only. See the <ref id="btaudio" +name="btaudio"> section for more information. + +<figure loc="here"> +<eps file="warning" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: Analog video capture cards are the only ones which +require a soundcard for capturing audio. DVB, HDTV, and other hardware +encoder cards all provide a combined audio / video stream. +</caption> +</figure> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Plugging a Line-level device into the Mic input is +not recommended. Line-level devices have higher voltages and can damage the +sound card. In addition, even if it doesn't break your card, you will be +getting Mono sound. See the Linux MP3 HOWTO at <url +url="http://www.tldp.org/HOWTO/MP3-HOWTO.html" +name="http://www.tldp.org/HOWTO/MP3-HOWTO.html"> for additional information. +</caption> +</figure> + +<sect2>Video Display Card +<p>MythTV will work with just about any video card. However, it is highly +recommended that you use a card which supports XVideo (XV) extensions. If +your card does not support XV, color conversion and scaling will be +performed by your CPU rather than the video card. This is very CPU +and memory intensive and will often result in dropped frames and a +corresponding degradation of quality. Check the X documentation +for details if you are uncertain about your preferred card. You may +also run <tt>xvinfo</tt>; look for your video card to be listed as one +of the adapters. + +<!-- Updated information from "Ray Olszewski" <ray@comarre.com> --> + +If you want to use MythTV with a standard television, you will need a +physical connection from your video card to your TV set, which can either be +a TV-out port on the card itself or an external adapter that converts the +VGA signal to an appropriate video signal. "Appropriate" depends on a number +of factors, such as video standard (NTSC vs. PAL), the type of input +connection (Composite vs. SVideo), etc. + +Note that with some video cards and X drivers, XVideo extensions are +only supported on the VGA output, and not on the TV output. + +<sect2>Cards with TV-out +<p>The next section deals with a number of cards that are known to have +TV-out ports. The list is unlikely to be complete, so if you know of +others, please post a message to the mythtv-users mailing list so the +information can be included in future versions of the HOWTO. The list is +organized by manufacturer. + +Reports here are based on what users of the cards have posted on the +mythtv-users mailing list, so if you need configuration details, please +search the archives at <url +url="http://www.gossamer-threads.com/lists/mythtv/" +name="http://www.gossamer-threads.com/lists/mythtv/"> using +the card name in your search string. + +<sect3>ATI +<p>ATI makes many cards with TV-out capability, but only offers Linux +drivers for Radeon 8500 and above cards. See the Drivers and Software +section of <url url="http://www.ati.com/" name="http://www.ati.com"> for the +driver and additional information. + +The enhanced ati.2 X driver created by the GATOS <url +url="http://gatos.sourceforge.net" name="http://gatos.sourceforge.net"> +project offers some support for TV-out on other ATI cards, but only in its +"experimental" version, available through CVS. There have been reports from +people who say they have made this driver work with one or another ATI card. +For example, Bruce Markey <url url="mailto:bjm@lvcm.com"> writes (on the +mythtv-users mailing list): "I got this to work. You can quote me on that. +I've used TV-out on several models of ATI cards both All-In-Wonder and +regular cards with TV-out." See the "Adventurous Setup" section of <url +url="http://gatos.sourceforge.net/watching_tv.php" +name="http://gatos.sourceforge.net/watching_tv.php"> for details. Also see +<url url="http://www.retinalburn.net/linux/tvout.html" +name="http://www.retinalburn.net/linux/tvout.html"> for more information. + +<sect3>NVIDIA +<p>Some NVIDIA cards with TV-out can be run using the standard nv driver in +X, combined with the userspace application <bf>nvtv</bf> to control the TV-out +port. See <url url="http://sourceforge.net/projects/nv-tv-out/" +name="http://sourceforge.net/projects/nv-tv-out/"> for details. Recent +versions of the NVIDIA driver have better support for overscan and other +features useful with TV-Out, so the <bf>nvtv</bf> application may not be +required. + +Some NVIDIA cards can be run with a proprietary NVIDIA X driver made +available by NVIDIA. See <url url="http://www.nvidia.com/object/unix.html" +name="http://www.nvidia.com/object/unix.html"> for more information. + +<bf>NOTE</bf>: It's strongly recommended that you use the proprietary +NVIDIA drivers; they have excellent support for XvMC and ship with a good +configuration utility. XvMC provides MPEG-2 hardware acceleration, which is +important if you want to display HDTV. + +<sect3>Hauppauge PVR-350 <label id="PVR-350"> +<p>MythTV supports the TV-out and MPEG-2 decoder functions in the IvyTV +driver. + +The PVR-350 is unique amongst the Hauppauge PVR-x50 cards in that it also +supports audio output, but you need to connect that audio output to +something. There are two courses of action you may take: +<enum> +<item>Take the audio output from the PVR-350 and plug it into an input on a +sound card on your machine. You may then use MythTV's internal audio +controls. +<item>Take the audio output from the PVR-350 and connect it directly to your +television / audio system. You must indicate that you are using external +audio control on the PVR-350 setup page. +</enum> + +<sect3>Other Options +<p>Some devices with on-board TV-out capability, such as Xboxes converted to +Linux and some laptops can be used as MythTV frontends to display on a +television screen. Please consult the mythtv-users mailing list for messages +that report the details of these special arrangements. + +<sect2>External Adapters +<p>External adapters convert standard VGA output to a form suitable for +display on a television. The output format varies by region, since +different countries have different TV standards. People on the mythtv-users +list have mentioned these adapters: + +<itemize> +<item>AITech Web Cable Plus, powered by external transformer or takes power +from PS/2 keyboard connector, support resolutions up to 1024x768, outputs +composite and SVideo, provides position adjustment. +<item>Averkey lite, powered by a USB port, has Composite, SVideo, YPbPr +outputs; pan, brightness, overscan/underscan controls; supports up to +1024x768 outputs; and supports PAL and NTSC. +<item>ADS TV Elite XGA +<item>AverKey iMicro (comments are generally favorable) +<item>AITech Web Cable (comments are generally unfavorable, different than +the "Plus" version above) +<item>TVIEW Gold (mentioned once, favorably) +</itemize> + +<sect1>Software +<p>There are a few ways of installing programs on Linux systems; you can +either use a pre-compiled package, or install from a tarball after +satisfying any prerequisites. + +<figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: you must have the MySQL database software installed on a +system to store the master database. This does not necessarily mean that +MySQL must run on one of the MythTV boxes. The minimum MySQL version is 5.0. +</caption></figure> + +<sect2>Pre-compiled packages <label id="precompiled"> +<p>A number of people have created pre-compiled packages for MythTV that may +make your installation easier. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +<bf>BIG FAT WARNING</bf>: This HOWTO assumes that you have <em>not</em> +installed MythTV from a package. All example command lines and file +locations are based on the MythTV tarball defaults. Some packagers have +modified the filenames, binaries and file locations to match what is +commonly found in that distribution. Any issues with MythTV installed via a +pre-compiled package <bf>MUST</bf> be raised with the packager. +</caption> +</figure> + +If you use any of the pre-compiled packages you may not need to perform any +additional configuration steps in this HOWTO. The next logical step is +<ref id="mysql" name="configuring MySQL">, which you may or may not have to +perform. See your package documentation. + +<sect3>Red Hat Linux / Fedora Core +<label id="atrpms"> +<p>The definitive documentation on installing MythTV on Red Hat Linux / +Fedora Core can be found in Jarod Wilson's (<url +url="mailto:jcw@wilsonet.com" name="mailto:jcw@wilsonet.com">) HOWTO at <url +url="http://wilsonet.com/mythtv/" name="http://wilsonet.com/mythtv/"> Just +like 3rd-party packages, any 3rd-party documentation problems should be +brought up with the 3rd-parties (maintainer, lists, bugzillas etc.). The +installation instructions which follow should be used as a guide only; refer +to Jarod's guide. + +Red Hat Linux and Fedora Core packages for MythTV and all of its add-on +modules and some themes have been packaged by <url +url="mailto:Axel.Thimm@ATrpms.net" name="mailto:Axel.Thimm@ATrpms.net"> and +are available at <url url="http://ATrpms.net/topic/multimedia/" +name="http://ATrpms.net/topic/multimedia/">. All of the prerequisites for +MythTV (such as XMLTV) are available as RPM packages. If you have problems +with the RPMs, please contact the ATrpms lists at <url +url="http://lists.ATrpms.net/" name="http://lists.ATrpms.net/"> or file a +bug against <url url="http://bugzilla.ATrpms.net/" +name="http://bugzilla.ATrpms.net/">. + +Given the large number of dependent RPMs you are advised to use tools like +apt or yum for automatic retrieval and installation of the required RPMs. +(<url url="http://ATrpms.net/install.html" +name="http://ATrpms.net/install.html">) In this case a +special meta-package called mythtv-suite will allow you to install all of +MythTV and its add-ons, plus all dependencies. + +If you don't have <bf>apt</bf> or <bf>yum</bf> on your machine, download and +install the atrpms-kickstart package from <url +url="http://ATrpms.net/name/atrpms-kickstart/" +name="http://ATrpms.net/name/atrpms-kickstart/">. +Install the package with: +<tscreen><verb> +# rpm -Uvh atrpms-kickstart* +</verb></tscreen> +Then run: +<tscreen><verb> +# apt-get update +# apt-get dist-upgrade +# apt-get update +</verb></tscreen> +And finally: +<tscreen><verb> +# apt-get install mythtv-suite +</verb></tscreen> +These steps however, do NOT perform the installation of any drivers required +for <bf>ALSA</bf>, capture cards, <bf>lirc kernel modules</bf>, etc., nor do +they set up your MythTV database. Check <url +url="http://ATrpms.net/topic/multimedia/" name="http://ATrpms.net/topic/multimedia/"> for the drivers you +need. + +<sect3>Mandriva +<p>Thac has created RPMs for MythTV for Mandriva which may +be obtained from <url url="http://rpm.nyvalls.se/" +name="http://rpm.nyvalls.se/"> If you have problems with the RPMs, please +send him email directly at <url url="thac@nyvalls.se" name="thac@nyvalls.se">. +<sect3>Debian +<p>Debian packages for MythTV and most of its add-on modules are maintained +by Christian Marillat <url url="mailto:marillat@free.fr" +name="mailto:marillat@free.fr"> and are available at <url +url="http://www.debian-multimedia.org/" +name="http://www.debian-multimedia.org/">. +Installation instructions can be found on those pages as well. All of the +prerequisites for MythTV are available as Debian packages, most of them from +the official Debian archive. + +If you have followed the instructions on the above page you should have added +<tscreen><verb> +deb-src http://www.debian-multimedia.org sid main +</verb></tscreen> + +to your <tt>/etc/apt/sources.list</tt> file. Running <bf>apt-get update</bf> and then +executing <bf>apt-get build-dep mythtv</bf> should install all the +pre-requisites required to compile MythTV. + +<figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: Due to the requirement for Qt 3.3+, there are no packages for +Debian woody/stable. +</caption></figure> + +<p>The Debian packages are configured such that MythTV programs should be +run as the <tt>mythtv</tt> user, which is automatically created during +installation. This user has access to write new recordings to disk in the +default directory, read and write the database, access the audio and video +devices, and everything else that MythTV needs to do. + +<p>See <tt>/usr/share/doc/<it>packagename</it>/README.Debian</tt> for more +information, including copies of the MythTV documentation. The +<tt>mythtv-doc</tt> package contains a copy of this HOWTO in +<tt>/usr/share/doc/mythtv-doc</tt>. +<sect2>Manual installation +<p>You may use the graphical tools that come with your distribution, or you +can use command-line utilities. Either system will get the job done, and it +all depends on your comfort level with Linux. + +In order to compile MythTV, we need to make sure that the software it needs +is installed. This list includes <bf>mysql</bf>, <bf>gcc</bf>, +<bf>freetype2-devel</bf>, <bf>xorg-xserver-devel</bf>, <bf>qt-devel</bf> and +<bf>lame</bf>. If you're going to use a remote control with MythTV, you're +going to need the <bf>cdialog</bf> package in order to compile +<bf>lircd</bf> if your distribution doesn't have a pre-packaged +<bf>lirc</bf>. If you are using <bf>XMLTV</bf> as a grabber, you will need +<bf>perl</bf>. + +<code> +NOTE: Qt v3.3 or higher is required. + +NOTE: MythTV DOES NOT WORK with Qt4. + +NOTE: If you are going to be using RPMs to install various +components, you should be aware that not all packages include the necessary +headers for compiling. If you're having trouble compiling, ensure +that you've installed the -devel version of a prerequisite. +</code> + +<sect2>Command-line installation <label id="CLIinstalltools_"> +<p> This section details the various methods for installing prerequisites +from the command line. + +<sect3>Mandriva +<p><bf>NOTE</bf>: The following instructions should be considered out of +date as of 2006-09-10. If updated instructions are not submitted by the +release of v0.21 of MythTV they will be removed. + +<bf>urpmi</bf> is the simplest tool for installation of packages from the +command line, but properly configuring it can be difficult. The +following website <url url="http://easyurpmi.zarb.org/" +name="http://easyurpmi.zarb.org/"> will allow you to choose +a mirror site and then present the command-line configuration text for that +mirror. You will most likely need to add a "Contrib" mirror to your setup. +If you add a site from the "Penguin Liberation Front", you will be able to +load the <tt>lame</tt> library without compiling from source. + +Open a shell, and execute the following. You may get +asked a number of questions regarding dependencies. It's best to answer +"YES". +<tscreen><verb> +$ su +# urpmi mysql gcc gcc-c++ freetype2-devel cdialog alsa-utils +# urpmi XFree86-devel perl +# urpmi libqt3-devel libMesaGLU1-devel +</verb></tscreen> + +<code> +NOTE for Mandriva 9.1+ users: execute the following command. + +# urpmi libqt3-mysql +</code> +However, you might get this when you execute the commands above: +<tscreen><verb> +everything already installed +</verb></tscreen> + +In that case, you're ready to move to the next <ref id="Setting_up_paths" +name="section">. Once you have completed installing the pre-requisites, +exit out of the shell and start a new one to ensure that any environment +variables setup by the installation have a chance to take effect. + +<sect3>Gentoo. +<p><bf>NOTE</bf>: MythTV does <em>not</em> run on Qt4. +If Qt has not been installed on your system: Edit +<tt>/etc/make.conf</tt> and locate the "USE" variable. If the line is +commented out, remove the comment. The line should have at least: +<tscreen><verb> +USE="mysql alsa" +</verb></tscreen> +Next you need to build Qt. If you don't plan on using the ebuilds as +described in the Gentoo section then you also need to install lame. +<tscreen><verb> +# emerge lame mysql qt +</verb></tscreen> + +If you have already installed Qt: you will need to rebuild because the +default installation doesn't include MySQL support, a requirement for MythTV. +To enable SQL support, add "mysql" to your USE variable in +<tt>/etc/make.conf</tt> and rebuild Qt by running +<tscreen><verb> +# emerge qt +</verb></tscreen> + +All the necessary files will be downloaded and built. Even on a fast machine +this may take a lot of time if you need to do a full Qt build. + +<sect3>Debian. +<p>Build-dependencies for MythTV can be satisfied by adding the following to +your <tt>/etc/apt/sources.list</tt> +<tscreen><verb> +# Christian Marillat's packages (mplayer, lame) +deb http://www.debian-multimedia.org sid main +deb-src http://www.debian-multimedia.org sid main +</verb></tscreen> +and executing: +<tscreen><verb> +# apt-get build-dep mythtv +# apt-get source mythtv --compile +</verb></tscreen> + +<sect>System Configuration Requirements for Compiling MythTV. <label +id="Setting_up_paths"> +<p>Before you compile MythTV from the current source tarball or from +<bf>subversion</bf>, you may need to modify your system configuration in a +few ways. + +In general, if you install MythTV from pre-packaged binaries for your Linux +distribution/version, you don't need to be too concerned about the issues in +this section of the HOWTO - the install script for the packages should take +care of them. However, this section is still recommended reading which may +help if the packager skipped a step in their packaging. + +<sect1>Software requirements for compiling MythTV +<sect2>General requirements +<p>MythTV is written in C++ and requires a fairly complete, but standard, +compilation environment, including a recent g++ compiler, <tt>make</tt>, and +appropriate header files for shared libraries. Any standard Linux +distribution should be able to install a suitable compilation environment +from its packaging system. Section 3.2 of this HOWTO provides some details +of how to install the required environment for many distributions. + +Subsequent sections of this chapter address the few oddities that you may +have to adjust by hand before you compile MythTV. + +The reference compilation system for MythTV is Ubuntu. + +<sect1>Shared-Library requirements for MythTV +<sect2>Modifying /etc/ld.so.conf <label id="modifying_ld.so.conf"> +<p>The runtime manager for shared libraries, <bf>/lib/ld.so</bf>, gets +information about the locations and contents of shared libraries from +<tt>/etc/ld.so.cache</tt>, a file created by <bf>ldconfig</bf> from +information in <tt>/etc/ld.so.conf</tt>. Because MythTV installs some +shared libraries in <tt>/usr/local/lib</tt>, that directory needs to be +added to the list of directories for <bf>ld.so</bf> to search when doing +runtime linking of programs, if it is not already there. +You do this, as root, by editing <tt>/etc/ld.so.conf</tt>, then +running <bf>ldconfig</bf>. There are many ways to do this; one that +works is to enter this series of commands: + +<tscreen><verb> +$ su - +# echo /usr/local/lib >> /etc/ld.so.conf +# /sbin/ldconfig +# exit +$ +</verb></tscreen> +<sect1>Environment variable requirements for MythTV +<sect2>General requirements +<sect3>QT libraries and binaries +<p>The compiler needs to be able to locate QT binaries and libraries in +order to compile MythTV. QTDIR needs to be set and the directory holding the +QT binaries needs to be added to your PATH. Your distribution may already +be making these changes as a part of the installation of the software +prerequisites detailed earlier. + +One way to do this is as follows: <label id="Checking_that_it_worked"> + +Open a shell and execute the following: +<tscreen><verb> +$ echo $PATH +/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/usr/games:/usr/lib/qt3/bin:/home/mythtv/bin:/usr/lib/qt3/bin +$ echo $QTDIR +/usr/lib/qt3 +$ which qmake +/usr/lib/qt3/bin/qmake +</verb></tscreen> + +For Mandriva, you should see a value like <tt>/usr/lib/qt3</tt> for +<tt>QTDIR</tt> and <tt>/usr/lib/qt3/bin</tt> should be in $PATH. + +For Gentoo, you should see a value like <tt>/usr/qt/3</tt> for <tt>QTDIR</tt> +and <tt>/usr/qt/3/bin</tt> should be in $PATH. + +If you don't, do not proceed past this step until you have resolved this +error. You may need to manually specify the QTDIR and PATH at the shell +prompt before compiling. + +Also, check that there has been a link created in +<tt>/usr/lib/qt3/mkspecs</tt> (<tt>/usr/share/qt3/mkspecs</tt> for Debian) +called <tt>default</tt>. If not, you'll get errors during the compile. See +the Troubleshooting Section for more information. +<sect2>Distribution-Specific Notes +<sect3>Mandriva +<p>The following instructions work for Mandriva using +<bf>bash</bf> as the shell, and may be applicable for a distribution which +uses <tt>/etc/profile.d</tt>. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Mandriva 10 installs a <tt>/etc/profile.d/qtdir3.sh</tt> +file, but it doesn't include the addition of the PATH variable. If you're +running Mandriva 10, don't create a <tt>mythtv.sh</tt> file as detailed +below; edit the <tt>qtdir3.sh</tt> file and add the PATH statement within +the if / fi block. +</caption> +</figure> +As root, create the following file in <tt>/etc/profile.d</tt> The example +filename is "mythtv.sh". Use what you feel is appropriate. + +Open a shell, and switch to superuser mode. + +<figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: ^D means press CTRL and d at the same time. +</caption> +</figure> +<tscreen><verb> +$ su +# cd /etc/profile.d +cat > mythtv.sh +export QTDIR=/usr/lib/qt3 +export PATH=$PATH:/usr/lib/qt3/bin +^D + +# chmod a+x mythtv.sh +# exit +$ exit +</verb></tscreen> +The last two commands are to exit out of the shell. This way, when you next +open a shell your new commands +will take effect. + +<sect2>Device Permissions <label id="devperms"> +<p>MythTV will need access to the video4linux devices on your system. By +default, your distribution may restrict access to these devices to the +logged-in user, so if you will be automatically starting +<bf>mythbackend</bf> from a script rather than an interactive terminal +session you will need to make some adjustments. + +<bf>NOTE</bf>: The following instructions are accurate for Mandriva. + +Check for a file called <tt>/etc/security/console.perms</tt>. Open the file +in your favorite text editor and look for a line that has: +<tscreen><verb> +<console> 0600 <v4l> 0600 root.video +</verb></tscreen> +and replace it with +<tscreen><verb> +<console> 0666 <v4l> 0666 root.video +</verb></tscreen> + +What we're doing is allowing read and write access to the files in the +video4linux directory. +<sect>Downloading and compiling. <label id="DownloadAndCompile"> +<p>Get MythTV from the <url url="http://www.mythtv.org" +name="http://www.mythtv.org"> web site. There are two installation methods +you may choose from. The first is to download the latest release in tarball +format and compile. The tarball release of MythTV should work on a wide +variety of systems and should be the preferred method for new users. If you +wish to use the <bf>subversion</bf> copy of MythTV you may obtain it from +<url url="http://svn.mythtv.org" name="http://svn.mythtv.org"> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: If you are going to use <bf>subversion</bf> to +compile MythTV rather than using the distribution tarball, you <em>must</em> +join the <url url="http://www.mythtv.org/mailman/listinfo/mythtv-commits/" +name="http://www.mythtv.org/mailman/listinfo/mythtv-commits/"> and <url +url="http://www.mythtv.org/mailman/listinfo/mythtv-dev/" +name="http://www.mythtv.org/mailman/listinfo/mythtv-dev/"> mailing lists to +keep up to date with the current status of the code. Code obtained from +subversion has no guarantees regarding stability, etc. +</caption> +</figure> + +If you are in North America you will use the Schedules Direct grabber which is +built-in to MythTV. You <em>do not</em> need to install XMLTV (so you may +skip XMLTV-related instructions), but you need <bf>wget</bf> version 1.9.1 +or higher. + +Get XMLTV from <url url="http://xmltv.sourceforge.net" +name="http://xmltv.sourceforge.net">. Download the latest version (0.5.51). + +<code> +NOTE for Mandriva users: If you have added a "PLF" mirror, you may skip the +next step and type: + +# urpmi libmp3lame0 libmp3lame0-devel + +After downloading, be sure to install both: +# rpm -Uvh lame* + +</code> + +Get lame from <url url="http://lame.sourceforge.net/" +name="http://lame.sourceforge.net/">. Download the source code to v3.96.1 +by following the links from "Using" through "Download...". + +<sect1>Building LAME +<p>Open a shell and switch to the directory where you saved lame. +<tscreen><verb> +$ tar -xzf lame-3.96.1.tar.gz +$ cd lame-3.96.1 +$ ./configure +$ make +$ make test +$ su +# make install +</verb></tscreen> +Check that it worked: +<tscreen><verb> +# ls -l /usr/local/lib +-rw-r--r-- 1 root root 381706 Nov 4 14:22 libmp3lame.a +-rwxr-xr-x 1 root root 674 Nov 4 14:22 libmp3lame.la* +lrwxrwxrwx 1 root root 19 Nov 4 14:22 libmp3lame.so -> +libmp3lame.so.0.0.0* +lrwxrwxrwx 1 root root 19 Nov 4 14:22 libmp3lame.so.0 -> +libmp3lame.so.0.0.0* +-rwxr-xr-x 1 root root 360197 Nov 4 14:22 +libmp3lame.so.0.0.0* + +# exit +$ +</verb></tscreen> + +<sect1>XMLTV +<sect2>Red Hat Linux and Fedora Core: +<p>RPMs for <bf>XMLTV</bf> and all of its dependencies can be obtained from +<url url="http://ATrpms.net/name/xmltv/" +name="http://ATrpms.net/name/xmltv/">. The web page has a +list of all the dependent packages you must download and install. +<tscreen><verb> +# rpm -Uvh xmltv* perl* +</verb></tscreen> + +If you install from this location you may skip to <ref id="manually_building_mythtv" +name="Manually building MythTV">. +<sect2>Mandriva +<p>RPMs for <bf>XMLTV</bf> and all of its dependencies are located in +Mandriva's "contrib". If you have added a contrib mirror, try installing +<bf>XMLTV</bf>: +<tscreen><verb> +# urpmi xmltv xmltv-grabbers +</verb></tscreen> +If this does not work, it is possible that contrib for your Mandriva version +does not have <bf>XMLTV</bf>, so you may install the XMLTV prerequisites by typing: +<tscreen><verb> +# urpmi perl-xml-twig perl-xml-writer perl-datemanip perl-libwww-perl +</verb></tscreen> + +and skip straight to the XMLTV compilation step. + +<sect2>Manual installation +<p> +<label id="untarring_xmltv">Untar the xmltv file: +<tscreen><verb> +$ tar -xjf xmltv-0.5.51.tar.bz2 +</verb></tscreen> +Install the xmltv prerequisites. The following prerequisites are the +minimum required; when you actually start running the xmltv setup program it +may alert you to other modules that are required.: + +<tscreen><verb> +$ su +# perl -MCPAN -e shell +cpan> install XML::Twig +cpan> install Date::Manip +Date::Manip is up to date. +cpan> install LWP +cpan> install XML::Writer +cpan> exit +</verb></tscreen> + +Change to the XMLTV directory and compile it: +<tscreen><verb> +$ cd xmltv-0.5.51 +$ perl Makefile.PL +</verb></tscreen> +You can answer "N" to the tv_check, tv_pick_cgi questions. Say "yes" to +the grabber required for your location. + +You may get errors about modules not being installed. You will need to +resolve any missing dependencies at this point, or your grabber may not work +correctly. +<tscreen><verb> +$ make +$ make test +$ su +# make install +# exit +</verb></tscreen> + +<sect1>Configuring the Schedules Direct service <label id="ConfigureSD"> +<p>As of 2007-09-01, Tribune Media Services will no longer offer free guide +data. Schedules Direct is a non-profit organization which has licensed the +data to make it available to users of Freeware and Open Source applications. + +If you wish to use Schedules Direct, you'll need to establish a user +account. Go to <url url="http://www.schedulesdirect.org" +name="http://www.schedulesdirect.org"> and click on the "Membership" link. + +Once you've read and agreed to the Subscriber Agreement, Terms of Use and +Privacy Policy proceed to the lineup choices and configure your account for +your particular location and the channels that you have. This configuration +will be imported into MythTV when you first run the <bf>mythtv-setup</bf> +program. + + +<label id="manually_building_mythtv"> +<sect1>Manually building MythTV +<p>If you are going to use <bf>subversion</bf>, execute the following +instructions to obtain the latest version of MythTV: + +<tscreen><verb> +$ mkdir mythtv +$ svn co http://svn.mythtv.org/svn/trunk/ mythtv +$ cd mythtv +</verb></tscreen> + +To use a release version, you can execute: +<tscreen><verb> +$ mkdir mythtv-release-0.21 +$ svn co http://svn.mythtv.org/svn/branches/release-0-21-fixes/ mythtv-release-0.21 +$ cd mythtv-release-0.21 +</verb></tscreen> + +<bf>NOTE</bf>: Using a svn version of the code allows you to stay +up-to-date with changes. So, if there's an update to the 0.21 release and +you originally obtained it using svn, you could enter the +mythtv-release-0.21 directory and type "svn up", which will update your copy +with the fixed version from the website. You would then recompile and +install the updated 0.21 code. + +If you are using the tarball, then unpack it: +<tscreen><verb> +$ tar -xjf mythtv-0.21.tar.bz2 +$ cd mythtv-0.21 +$ ./configure +</verb></tscreen> + +If you wish to change options, run <bf>./configure --help</bf> to +see what is available and to override and automatically detected options. +See the <tt>config.log</tt> file after running <bf>configure</bf> to see +previous runs. + +To compile: +<tscreen><verb> +$ make -j 2 +</verb></tscreen> + +The MythTV compile can take advantage of multiple CPUs, SMP and +Hyperthreading. If you want to build MythTV on a multi-CPU machine (or with +<bf>distcc</bf>), specify "-j numjobs", where "numjobs" is greater than 2. +In the above example, we had two concurrent jobs executing, which is +recommended for a single CPU system. Do not set the number of jobs too +high, or your compile will actually take longer to complete than it would if +you did a "normal" build. + +If you are using <bf>distcc</bf>, and you had two other host machines (red, blue) +participating, you would do something like: +<tscreen><verb> +$ export DISTCC_HOSTS='localhost red blue' +$ make -j 6 CXX=distcc +</verb></tscreen> + +The actual speed-up, if any, is dependant on a number of factors, such as +number of CPUs / hosts, etc. The <bf>distcc</bf> documentation recommends +using a <tt>-j</tt> value of twice the number of CPUs available to keep all +of them busy. + +Some timing information. The following should only be used for +illustration; your actual results may vary. The test involves a complete +<tt>make distclean</tt> to the final binary. +<itemize> +<item>P4 3.2Ghz HT: "standard" make: 12m 49s +<item>P4 3.2Ghz HT: make -j 2: 11m 24s +</itemize> + +In the above example, we see that with a single CPU, a multi-stage +<bf>make</bf> does not significantly decrease compile time. + +Once the compile is done, switch to superuser: +<tscreen><verb> +$ su +# make install +# exit +</verb></tscreen> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: subsequent configuration steps assume that you are within +the MythTV directory that you <tt>cd</tt>'d to above. +</caption> +</figure> + +<sect2>Enabling real-time scheduling of the display thread. +<p>MythTV supports real-time scheduling of the video output thread. There +are three ways to go about enabling this: You can use rlimits, you can use +the realtime security module, or on older systems you can SUID the +executable. Enabling real-time scheduling is optional, but can make the +video display smoother, especially if you are decoding HDTV. + +<sect3>rlimits +<p>The rlimits method is the preferred method and is included in Linux +2.6.12 and above. Unfortunately, you need PAM version 0.79 or above, which +may not be supported by your distribution yet. Assuming anyone running +<bf>mythfrontend</bf> is in the audio group and rlimits are supported, all +you need to do is place this in your <tt>/etc/security/limits.conf</tt> + +<tscreen><verb> +* - rtprio 0 +* - nice 0 +@audio - rtprio 50 +@audio - nice 0 +</verb></tscreen> + +<sect3>realtime module +<p>The second option is to use the Linux realtime kernel module. +This is will be phased out over time, but is currently supported +by many distributions that do not yet support rlimits. If you are +not using the distribution kernel you must configure your kernel +with: +<tscreen><verb> +Security options : [*] Enable different security models +Security options : [M] Default Linux Capabilties +</verb></tscreen> +You may also need to install the realtime module, using your distribution's +realtime package. Assuming the users who will be running +<bf>mythfrontend</bf> will be in the audio group you can get the GUID of a named +group like so: +<tscreen><verb> +$ grep audio /etc/group +</verb></tscreen> +If the number printed out from the grep was 18, you can now load +this module as root before starting <bf>mythfrontend</bf>: +<tscreen><verb> +# modprobe realtime gid=18 +</verb></tscreen> + +<sect3>run as root option (not safe) +<p>The final and least preferred option is to set the sticky bit +on the <bf>mythfrontend</bf> executable. This <bf>opens a security hole</bf>, +but is the only option on systems that do not support either +rlimits or the realtime module. This does not work on modern +distributions either, and is <bf><em>not recommended</em></bf> +on any system connected to the Internet. This may also make it +impossible to debug MythTV without running <bf>gdb</bf> as root. If you +would still like to do this, you just need to run this as root: +<tscreen><verb> +# chmod a+s /usr/local/bin/mythfrontend /usr/local/bin/mythtv +</verb></tscreen> + +<sect2>Frontend-only configuration <label id="frontend-only"> +<p>Since MythTV uses a client/server architecture, multiple frontend +computers can simultaneously access content on a Myth system. Live TV, +watching and scheduling recordings, etc. are all possible from multiple +frontends. + +To get a better picture of what is needed to run a frontend, note the +following: +<list> +<item>You do NOT need the MySQL server installed on your remote frontend +<item>You do NOT need XMLTV installed on your remote frontend +<item>You do NOT need to run the mythtv-setup program on +your frontend machine +</list> + +Other than the exclusion of the MySQL server and XMLTV, the MythTV +compilation procedure is the same as when you're setting up both a backend +and a frontend. However, you <em>will</em> need to install the database +access libraries. + +Once MythTV is compiled and installed: +<list> +<item> +Run the mythtv-setup program on your Master backend. Under the "General" +menu, change the IP address of the current machine (by default, "127.0.0.1") +to the real external IP address - 127.0.0.1 is the loopback address and no +external machine can access it. Change the Master Server IP setting to the +same IP address as well. +<item> +Run the mythfrontend program on your frontend machine, +and a "Database Configuration" screen should appear. +Set the "Host name" field to point to your Master backend's IP address. +</list> + +<sect1>Gentoo <label id="Gentoo_build"> +<p>Installation of MythTV on Gentoo consists of simply emerging the desired +ebuild because all of the packages are now part of the official Portage tree. +<tscreen><verb> +$ su - +# emerge --sync # make sure portage is up to date. +# vi /etc/make.conf +</verb></tscreen> +Add mysql to your USE variable. i.e. <tt>USE="mysql ...."</tt> +<tscreen><verb> +# emerge mythtv +</verb></tscreen> +<sect>MySQL.<label id="mysql"> +<p>When you install MySQL 5.x you will also want to comment +out "log-bin" in your <tt>my.cnf</tt> configuration file. This option will +quickly fill your "/var" disk partition with many gigabytes of data, +unless you are doing database replication and deleting these files regularly. +<sect1>Distribution-specific information +<sect2>Mandriva +<p>If this is the system maintaining the database, make sure that MySQL is +running and started at boot. Click on Mandriva Control +Center->System->Services, find MySQL and click the "On Boot" button and the +"Start" button if the MySQL status shows that it isn't running yet. + +<figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: There have been reports that MySQL isn't starting at boot. +If this is happening to you, try running the following commands. +</caption> +</figure> +<tscreen><verb> +$ su +# chkconfig --level 35 mysql on +# /etc/rc.d/init.d/mysql start +# exit +</verb></tscreen> + +<sect2>Red Hat Linux and Fedora Core +<p>If this is the system maintaining the database, make sure that MySQL is +running and started at boot. Click on Redhat menu>Server Settings>Services +and enter the root password when asked. Check "mysqld" and then click Start. +Click Save, then close the window. + +This can be done from the command line by typing: +<tscreen><verb> +# /sbin/chkconfig mysqld on +# /sbin/service mysqld start +</verb></tscreen> + +<sect2>Gentoo +<p>After installing MySQL you need to initialize the database by running +<bf>mysql_install_db</bf> as root. +<sect1>Setting up the initial database +<p>This step is only required on the system maintaining the database, which +may or may not be one of your MythTV boxes. If the database is on a +non-MythTV machine you'll need to copy the <tt>database/mc.sql</tt> file to it. + +To setup the initial MySQL databases: +<tscreen><verb> +$ cd database +</verb></tscreen> +<sect2>Mandriva and Red Hat Linux/Fedora Core +<p><tscreen><verb> +$ mysql -u root < mc.sql +</verb></tscreen> +<sect2>Debian 3.0 +<p><tscreen><verb> +$ mysql < mc.sql +</verb></tscreen> +<sect2>Gentoo +<p><tscreen><verb> +$ su +# mysql < /usr/share/mythtv/database/mc.sql +</verb></tscreen> +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: It is good practice to set a root password for MySQL. +Instructions for doing so can be found on MySQL's web site at <url +url="http://www.mysql.com/doc/en/Security.html" +name="http://www.mysql.com/doc/en/Security.html">. +</caption> +</figure> +<sect2>Modifying access to the MySQL database for multiple systems <label +id="modify_perm_mysql"> +<p>If you're going to have multiple systems accessing a master database, +you must grant access to the database from remote systems. By default, the +<tt>mc.sql</tt> script is only granting access to the local host. + +To allow other hosts access to your master database, you can either set it +up for no security at all, or with more granularity. Note that the "%" is +the wildcard character in MySQL. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: The "no security" option is <em>very</em> dangerous unless +you're in a controlled environment. +</caption> +</figure> +This example has no security at all, and allows access from any host. +<tscreen><verb> +$ mysql -u root mythconverg +mysql> grant all on mythconverg.* to mythtv@"%" identified by "mythtv"; +mysql> flush privileges; +</verb></tscreen> + +For a more secure setup, you can restrict which machines or subnets have +access. If you have a complete DNS system operational, you could do the +following: +<tscreen><verb> +$ mysql -u root mythconverg +mysql> grant all on mythconverg.* to mythtv@"%.mydomain.com" identified by "mythtv"; +mysql> flush privileges; +</verb></tscreen> + +Finally, if you just want to restrict by IP subnet (in this example, the +192.168.1. network): +<tscreen><verb> +$ mysql -u root mythconverg +mysql> grant all on mythconverg.* to mythtv@"192.168.1.%" identified by "mythtv"; +mysql> flush privileges; +</verb></tscreen> + +You'll also need to check that the "networking" feature of MySQL is turned +on. Check that <tt>/etc/mysql/my.cnf</tt> <em>does not</em> contain +<tt>skip-networking</tt>. If it does, remove it. Also verify that +<tt>bind-address</tt> is set to your IP address instead of +<tt>127.0.0.1</tt>. If you change either of these items, restart +<bf>MySQL</bf>. + +<bf>NOTE</bf>: Your distribution may have a customized MySQL configuration +file; in Mandriva, check <tt>/etc/sysconfig/mysqld</tt> for additional +configuration. + +<sect>Configuring Sound. +<p>If your video doesn't appear to be in-sync with your audio and you're +using an analog video capture card and a soundcard to capture audio, it +could be because you are listening to the real-time audio from your video +card rather than after it's been processed and synchronized to the video by +MythTV. Because MythTV is a personal video recorder, "Live TV" isn't really +live - to let you pause live TV, MythTV is actually encoding the video, +saving to disk, and then playing it back. This procedure puts your MythTV +"live" TV about 2 seconds behind real-time, so it's important that you're +not listening to the live audio. However, if you're having an issue where +the audio and video aren't synchronized by small but varying amount, it's +most likely because the sound driver that you're using doesn't have the +DSP_CAP_REALTIME capability. This was the case with ALSA (0.5), but not +with newer versions. See the <ref id="Troubleshooting_Audio" +name="Troubleshooting Audio"> section for more information if you're having +issues with sound. Also, ensure that no other programs are grabbing the +audio output, like <bf>arts</bf> or <bf>esd</bf>. + +What you need to do is to mute the "line-in" of your sound card and also +set it as the recording source. + +There are two ways to do this. Graphically, and from the command line. + +<sect1>Graphically setting up the mixer +<sect2>Mandriva and Red Hat Linux/Fedora Core +<p>Open Kmix by clicking K->Multimedia->Sound->Kmix for Mandriva, or +<verb>RedHat Menu>Sound & Video>Volume Control</verb> on Red Hat/Fedora. + +Click on Settings->Configure Make sure that "Tick Marks" and "Show +labels" have "X"'s in them. This will make it easier to find the correct +audio source. Click OK. + +On the mixer page, look for Line-In on your sound card. You should see +two LED's - a green one at the top, and a red one at the bottom. The green +one at the top is for muting; you want to make sure that the green LED is a +dark green, meaning that it's "off". You also want to click on the red LED +so that it turns bright red, indicating that it's "ON"; this insures that +the Line-in is used as the source. Click OK, and make sure that you save +the settings so that this is your default. + +<sect3>Using ALSA. +<p>To use ALSA, you'll need to correctly setup your +<tt>asoundrc</tt> file. Configuring this file is beyond the scope of this +HOWTO. Once ALSA is working correctly, change the output sound device in +mythfrontend->setup->Audio from <tt>/dev/dsp</tt> to <tt>ALSA:default</tt>. +This field may be edited to suit your ALSA requirements. + +<sect1>Setting the mixer from the command line +<p>If you have installed the alsa-utils package, then the <bf>amixer</bf> +program can be used to setup the mixer. The "Master" volume setting is only +required on a frontend machine to ensure that the sound channels are unmuted +and configured for outputting sound. The "Line" and "Capture" controls are +required for your sound card to actually capture audio from the external +Line-in if it's connected to an analog frame grabber. Not all sound cards +have a "Capture" control, but if yours does and you don't set it then MythTV +will not capture audio. + +<code> +Note the spelling in the following commands. +</code> +<tscreen><verb> +$ amixer set Master,0 100%,100% unmute +$ amixer set PCM,0 100%,100% unmute +$ amixer set Line,0 75%,75% mute captur +$ amixer set Capture,0 100%,100% captur +$ su +# alsactl store +# exit +$ +</verb></tscreen> + +If you have multiple sound cards, then use the <tt>-c</tt> parameter to +specify which card to adjust. Note that the first card will be "0", the +second will be "1", etc. + +That takes care of setting the volume correctly, and the ALSA startup script +will restore the volume after a reboot. If you find that your sound is +distorted, it's possible that the levels in the above examples are too high +for your particular hardware combination. Try reducing the percentages by +5-10% and checking again. Once you're satisfied, re-run the <tt>alsactl +store</tt> command. + +You may also use the <bf>alsamixer</bf> program to set the volume. If you +are using an ALSA version after 1.0.6, use <bf>alsamixer -V all</bf> First, +start <bf>alsamixer</bf> from the command line. You should start out on the +"Master" volume control slider. Use the up and down cursor to set the +master volume to around 75%. Next, use the left and right cursor keys to +move around on the screen until you find the "Line" slider. Press SPACE to +set it as the capture source, set the level to around 50-75% and press "M" +to mute it. You can now press ESC to exit out of the <bf>alsamixer</bf> +program. You can also have MythTV manage all volume and mute settings, but +this will only affect the "Master" or PCM volume, not the capture volume. See +the mythfrontend setup page for options. + +Finally, if you've performed all of the above steps, and you still don't seem to have any sound, it's possible that your video capture device is muting the audio output. +<tscreen><verb> +$ v4lctl -c /dev/video0 setattr mute off +</verb></tscreen> + +<sect>Setting up a remote control. +<p>MythTV does not have native remote control receiver and decoder software +built-in. Instead, remote control functions are implemented by cooperating +with <bf>lirc</bf>, the Linux Infrared Remote Control program. <bf>lirc</bf> +handles the IR hardware and passes keystrokes to MythTV, which then acts as +if the user had pressed the keys on the keyboard. The file +<tt>keys.txt</tt> describes the keys used to control MythTV. + +<figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: If you are running Mandriva, you may install +<bf>lirc</bf> by executing: <tt># urpmi lirc lirc-remotes</tt> and bypass +the manual compilation steps described below by jumping to the <ref +id="completing_lirc_install" name="Completing the lirc install"> section. +See the contrib/mandrake91.etc.sysconfig.lircd file for an example of how to +configure lircd. +</caption> +</figure> + +Some IR devices require a kernel recompile, and some don't. However, all at +least require having the kernel source available as a resource for the lirc +build process. + +<sect1>Gentoo +<p>To install lirc on Gentoo, all you need to do is: +<tscreen><verb> +# emerge lirc +</verb></tscreen> + +<sect1>Obtaining and compiling lirc +<p>You're going to need to download and compile <bf>lircd</bf>. Go to <url +url="http://www.lirc.org" name="http://www.lirc.org"> and download lirc; as +of 2006-01-21, the version available is 0.8.0. Grab the remotes.tar.bz2 file as +well. +<tscreen><verb> +$ tar -xjf lirc-0.8.0.tar.bz2 +$ cd lirc-0.8.0 +$ ./setup.sh +</verb></tscreen> +You're going to need to know what sort of receiver you have and where it's +connected. In the case of the Pinnacle Studio TV card, with the IR receiver +connected to COM1 (/dev/ttys0), once the configuration menu comes up, +perform the configuration by going to Driver Configuration->Other Serial +Port Devices->Pinnacle Systems Receiver->OK and on the next page select +COM1->OK. + +Each remote is different; some remote receivers connect directly to your +capture card and not to a serial port, so make sure that you've got the +correct one. + +You then click "Save Configuration and run configure" to continue. + +Make sure you read the last text generated by the configure step. It will +tell you if you require a kernel recompile, and what the name of your kernel +module will be (if necessary). For instance a home-built receiver may +require a kernel recompile, so you would be notified that you will have to +load the lirc_serial module. If you did not get any such messages skip the +kernel recompile steps below and go directly to making and installing the +lirc driver. + +Once the configuration step is complete: +<tscreen><verb> +$ make +$ su +# make install +# chmod 666 /dev/lircd +</verb></tscreen> + +At this point, if you're using a serial receiver, check that there's a +<tt>lirc</tt> device in <tt>/dev</tt>: +<tscreen><verb> +$ ls -l /dev/li* +lr-xr-xr-x 1 root root 5 Jan 27 09:00 /dev/lirc -> ttyS0 +srw-rw-rw- 1 root root 0 Jan 27 15:01 /dev/lircd= +prw-r--r-- 1 root root 0 Jan 27 09:00 /dev/lircm| +</verb></tscreen> + +As you can see, there's a link from /dev/lirc to ttyS0, a.k.a. "COM1", which is +appropriate for the Pinnacle Systems PCTV Pro. However, you may notice +something like this: +<tscreen><verb> +crw------- 1 root root 61, 0 Dec 31 1969 lirc +</verb></tscreen> +Some IR receivers (including some homebrew units) use a character device as +their data interface as opposed to a link to a serial port. If the <tt>make +install</tt> step has created a character device for you, don't replace it +with a link to a COM port. + +So, if the link or character device was not created (but should have been), +ensure that you ran the <tt>make install</tt> step as root. If it still +doesn't work, then there are three options. The first option is to re-read +the <bf>lirc</bf> documentation to determine whether your IR receiver is a +character device or should be a link to a serial port and to create the +link/character device manually. In this example, the IR device is connected +to ttyS0. If it were connected to "COM2", then use ttyS1, etc. +<tscreen><verb> +$ su +# cd /dev +# ln -sf ttyS0 lirc +# exit +$ +</verb></tscreen> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: The above example assumes that your receiver uses the +standard serial driver. Some receivers do not, including receivers that +plug into a TV capture card. Check the lirc documentation, but it may be +necessary to replace the link created above with a character pipe: +</caption> +</figure> +<tscreen><verb> +# mknod /dev/lirc c 61 0 +</verb></tscreen> + +See the lirc documentation for additional information. The lirc +installation <em>should</em> create this for you, so manually creating it +indicates that your lirc installation may have other issues. + +The second option is to post your issue to the <em>lirc</em> list, not the +mythtv-users list. The lirc programmers will be the ones that can assist +you best. + +The third option is to dispense with lirc altogether by purchasing an IR +keyboard (various options exist, although Chicony appears to work for some +people) and a learning remote control. The IR keyboard receiver plugs into +the PS/2 keyboard port on your PC and you would train your learning remote +to emulate the various keystrokes from <tt>keys.txt</tt> of your IR +keyboard. Using this method removes lirc entirely from the picture - your +remote will be sending keypresses that your PC "sees" on the keyboard port. + +<sect1>Completing the lirc install <label id="completing_lirc_install"> +<p><figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE to Mandriva 9.1 users</bf>: skip to the manual start paragraph +below. +</caption> +</figure> +<p>If the lirc configure program / compile did not mention anything about a +kernel module, then you are finished. If it did mention a kernel module, you +must edit the <tt>/etc/modules.conf</tt> file. Add this line as the first +thing in the file. It must come first, or it may not work. +<tscreen><verb> +alias char-major-61 XXX +</verb></tscreen> + +replace XXX with the name which you determined earlier, which in this +example was "lirc_serial" +<tscreen><verb> +$ su +# modprobe lirc_serial +# /sbin/ldconfig +</verb></tscreen> + +Next, we're going to manually start lircd the first time. Mandriva 9.1 +users, type: <tt># /etc/rc.d/init.d/lircd start</tt> instead of: +<tscreen><verb> +# /usr/local/sbin/lircd +</verb></tscreen> + +<bf>NOTE</bf>: Read this next section if you're not familiar with how lirc works! + +There are two separate files used by lirc, and both are required for your +remote control to do anything useful. First is the <tt>lircd.conf</tt> file. +<tt>lircd.conf</tt> tells the lirc daemon how to interpret the IR pulses +that it receives from a remote control and what name to assign to each +sequence of pulses. Without getting too involved, a particular series of +pulses may correlate to "Channel Up". The <tt>lircd.conf</tt> file will +then contain a line that looks something like this: + +<tscreen><verb> + ChannelUp 0x0000000000001020 +</verb></tscreen> + +The <tt>lircd.conf</tt> file can have multiple remote controls defined. + +The second file is <tt>lircrc</tt>, which takes the name of the button which +was pressed ("ChannelUp") in the above example, and correlates that to an +action to be performed by a program using the remote control. So in MythTV, +ChannelUp means one thing, while in <bf>mplayer</bf> it means something +different. <tt>lircrc</tt> gives you the flexibility of taking the name of +the button and having it perform different actions depending on which +program you're using at the time. + +<bf>NOTE</bf>: The definitions in <tt>lircd.conf</tt> come from the user +community, and there is no standard for the common button names. One +<tt>lircd.conf</tt> file may contain a definition for a button called +"ChannelUp", while another may contain a definition for "Chan+". Your +<tt>lircrc</tt> file must therefore be configured appropriately, or it won't +work. + +If this fails, complaining of a missing <tt>lircd.conf</tt> file, then you +must find or make one. First look for a pre-made configuration file at <url +url="http://lirc.sourceforge.net/remotes/" +name="http://lirc.sourceforge.net/remotes/">. Mandriva 9.1 users, look in +<tt>/usr/share/lirc-remotes</tt>. If you find one your remotes either on the +website or in <tt>/usr/share</tt>, download or copy the file, name it +<tt>lircd.conf</tt> and put it in your <tt>/etc</tt> directory. If you +couldn't find your remote, you must make your own <tt>lircd.conf</tt> file. + +To make your own <tt>lircd.conf</tt> file +<tscreen><verb> +$ irrecord myremote +</verb></tscreen> + +Follow the on-screen directions to train your remote and define keys. If +your remote ends up working well, you should consider submitting your +<tt>lircd.conf</tt> file back to the lirc developers. Once finished: +<tscreen><verb> +$ su +# cp myremote /etc/lircd.conf +</verb></tscreen> + +now try to start lircd again: +<tscreen><verb> +# /usr/local/sbin/lircd +</verb></tscreen> + +Now, we're going to add the commands necessary for lircd to run each time we +boot. Mandriva 9.1 users, you can execute: +<tscreen><verb> +$ su +# chkconfig --level 35 lircd on +# exit +</verb></tscreen> + +All other distributions: +<tscreen><verb> +# cd /etc/rc.d +# cat >> rc.local +echo "Starting lircd" +/usr/local/sbin/lircd +^D +# exit +$ +</verb></tscreen> + +This takes care of the lircd portion, which "listens" for the IR signals. If +everything went well, the install script for lircd put an appropriate +configuration file for your remote into <tt>/etc/lircd.conf</tt> This file +maps the buttons on the remote control to the IR pulses coming from the +receiver. + +The next step is to convert those signals into something that can be used +to control MythTV. MythTV now includes native support for lirc and can +interact directly with + +<tscreen><verb> +$ cd ~/mythtv-0.21/contrib/configfiles +$ cp lircrc.example ~/.lircrc +</verb></tscreen> +or +<tscreen><verb> +$ cp lircrc.example.pinnaclestudiopctv ~/.lircrc +</verb></tscreen> +if you've got a Pinnacle Studio PCTV remote. +<tscreen><verb> +$ irw +</verb></tscreen> +Start pressing the keys on your remote; <bf>irw</bf> will +print the name of the button as it is defined in your +<tt>/etc/lircd.conf</tt>. If you don't see anything at this point, you need +to troubleshoot further by going back to the lirc home page and investigating +from there. + +If it is working, then press <bf>CTRL-C</bf> to abort the program. Once you +know that your remote is working, you can either recompile MythTV with +native lirc support by enabling it in <bf>configure</bf> or you +need to run the <bf>irxevent</bf> program, which takes the key presses and +sends them to MythTV. If you use native lirc support, you don't need to run +<bf>irxevent</bf>. If you are going to use irxevent, then you need to run +it like this: +<tscreen><verb> +$ irxevent & +</verb></tscreen> +If <bf>irxevent</bf> isn't running, then MythTV will not respond to your remote +control unless you're using native lirc support. + +<sect1>Additional information for lirc +<p>Take a look at the lircrc.example files in the <tt>contrib/configfiles/</tt> +directory. In my case, (Pinnacle Studio card) the channel up and down functions +weren't working, due to the fact that the button names were different than +the default <tt>lircrc.example</tt> file that came with MythTV. + +The <tt>lircrc.example</tt> file has this: +<tscreen><verb> +begin + prog = irxevent + button = ChannelUp + config = Key Up CurrentWindow +end + +begin + prog = irxevent + button = ChannelDown + config = Key Down CurrentWindow +end +</verb></tscreen> +but the <tt>/etc/lircd.conf</tt> that comes in the lircd package +defines the buttons for the Pinnacle Studio PCTV as: +<tscreen><verb> + channel+ 0x0000000000000017 + channel- 0x000000000000001C +</verb></tscreen> +rather than "ChannelUp" and "ChannelDown". I added the +following to my /home/[yourusername]/.lircrc file: +<tscreen><verb> +begin + prog = irxevent + button = channel+ + repeat = 3 + config = Key Up CurrentWindow +end + +begin + prog = irxevent + button = channel- + repeat = 3 + config = Key Down CurrentWindow +end +</verb></tscreen> +which took care of basic functionality. Because the PCTV Studio remote +has additional buttons, look at the +<tt>contrib/configfiles/lircrc.example.pinnaclestudiopctv</tt> for an example of how +to define additional buttons, and how to debug potential button name +conflicts between the <tt>lircrc.example</tt> file and how <bf>your</bf> +remote defines the button names. + +By examining the button names defined in <tt>/etc/lircd.conf</tt> and using +the <bf>irw</bf> program to make sure that your remote is working, you can +create the appropriate mappings in <tt>.lircrc</tt> to get excellent remote +functionality with MythTV. + +Note the <bf>repeat =</bf> parameter. This informs the <tt>irxevent</tt> +program to pass through every third keypress. By default, <tt>lirc</tt> +will only send one keypress to the application, even if you're holding down +the key. The actual <bf>repeat =</bf> number will vary from system to +system, so experiment and see which value works best for you. + +<sect1>Configuring lirc for use with an IR blaster +<p> +<!-- By Carlos Talbot, <url url="mailto:carlos@talbot.net"> --> +Lirc has support for various IR transmitters. A popular model is the Actisys +IR-200L <url url="http://store.snapstreamstore.com/accessories.html" +name="http://store.snapstreamstore.com/accessories.html">. It was +originally designed for IRDA communication, but can be used to transmit A/V remote +control codes. By using the lirc SIR driver, this device can easily be +integrated with MythTV. I have tested this device with an AT&T DCT2000 +digital cable box but the instructions can be used to configure other IRDA +devices and A/V remotes. + +Follow the steps in the previous section. When you run setup.sh, select +option 1, driver configuration. From here select option 6, IrDA hardware. +Select your appropriate device and the corresponding serial port, then Save +configuration & run configure from the main menu. Once configure is done +type: +<tscreen><verb> +$ make +</verb></tscreen> + +Please note: unlike the Pinnacle receiver above you will be compiling lircd +in addition to a kernel module for the SIR transmitter. Depending on whether +you have your serial port driver configured as a kernel module you might see +the following message during make: +<tscreen><verb> +lirc_sir.c:56:2: warning: #warning +"******************************************" + +lirc_sir.c:57:2: warning: #warning "Your serial port driver is compiled into " + +lirc_sir.c:58:2: warning: #warning "the kernel. You will have to release the " + +lirc_sir.c:59:2: warning: #warning "port you want to use for LIRC with:" + +lirc_sir.c:60:2: warning: #warning "setserial /dev/ttySx uart none" + +lirc_sir.c:61:2: warning: #warning +"******************************************" +</verb</tscreen> + +If you do receive this statement make sure to run the <bf>setserial</bf> command +before you load the lirc_sir module. Follow this with the install: +<tscreen><verb> +$ su +# make install +</verb></tscreen> + +You will notice that lirc installs the kernel module in +<tt>/lib/modules/uname -a/misc</tt>. + +The configuration for starting <bf>lircd</bf> differs if you're going to be +sending and receiving IR versus just receiving. +<tscreen><verb> +# cd /etc/rc.d +# cat >> rc.local +echo "Starting lircd" +setserial /dev/ttySx uart none # (if required) +modprobe lirc_sir +/usr/local/sbin/lircd +^D +# exit +$ +</verb></tscreen> + +At this point you have to populate the <tt>/etc/lircd.conf</tt> file with the proper +codes for your A/V remote. You should be able to find your remote within the +lirc remote tar file located at <url +url="http://www.lirc.org/remotes.tar.bz2" +name="http://www.lirc.org/remotes.tar.bz2">. In my case I +extracted the file from remotes/motorola/DCT2000 (gi-motorola-dct2000) + +To test the lirc_sir module you can run <bf>irw</bf> to verify the codes are being +received. If everything is configured correctly +you should see something similar to the following: +<tscreen><verb> +$ irw +0000000000007ff0 00 1 gi-motorola-dct2000 +000000000000bff8 00 2 gi-motorola-dct2000 +000000000000f7f0 00 ENTER gi-motorola-dct2000 +</verb></tscreen> + +Once you've verified lirc is working you can press <bf>CTRL-C</bf> to exit +<bf>irw</bf> and configure the channel changing script. + +The path to the channel changing script will need to be entered on the +mythtv-setup screen for Input Connections. + +This csh script will be called each time MythTV needs to change the channel. +Below is a copy of the script followed by the corresponding perl script. +Make sure both are in your path. Also make sure you leave the #!/bin/csh +setting and not change it to Bourne or bash. This will create a frustrating +symptom to diagnose where MythTV cannot open /dev/device. Unlike Bourne or +bash, csh scripts automatically close parent file descriptors before they +start. +<tscreen><verb> +$ cd /usr/local/bin +# su +# cat > change_channel.csh +#!/bin/csh +echo "changing to $1" +/usr/local/bin/channel.pl $1 & +^D +# chmod a+x change_channel.csh +# exit +$ exit +</verb></tscreen> + +See <tt>contrib/channel.pl</tt> for the actual file. Copy it to +<tt>/usr/local/bin/</tt> + +The last statement within the perl script is the lirc rc command. This is +the command that transmits the code to your cable/DSS box. Make sure to have +the IRDA device within a few feet of the box. + +<sect>Configuring MythTV. <label id="Configuring_mythtv"> +<p>By this point, all of the compile-time prerequisites have been installed, +<bf>mysql</bf> is running and has had its initial database setup. It's now +time to configure MythTV. +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: If you're running Debian unstable and you have compiled +MythTV from source, you will need to install an additional package before +you will be able to run MythTV. Execute the following to install the MySQL +driver for QT. +</caption> +</figure> +<tscreen><verb> +$ su - +# apt-get install libqt3c102-mt-mysql +# exit +</verb></tscreen> +<sect1>Configuring the Master backend system +<p>Open a shell and decide where you will store your video files. This may +be one directory or multiple directories on the same or different +filesystems. There is no default directory used for new recordings, you +<bf>must</bf> create at least one storage directory and configure Myth to +use it by running <bf>mythtv-setup</bf>. If you do not do this, then MythTV +will be unable to record anything. The following example is specific for +<tt>/var/video</tt>, but the same instructions would apply for any directory +name you choose to use. See the <ref id="advancedpartitionformatting" +name="Advanced Partition Formatting"> section for hints on creating a +partition for MythTV. + +<tscreen><verb> +$ su +# mkdir /var/video +# chmod a+rwx /var/video +# exit +</verb></tscreen> + +<bf>NOTE</bf>: The last slash "/" is not required. + +<label id="storagegrouptip"> +<bf>TIP</bf>: Try not to have your video mount point on the same partition +as your root partition, which could lead to the filling up of your root +partition with video data if the mount fails. For example: + +If <tt>/var/video</tt> is created on your root partition and you then +perform a mount of another drive to this directory there won't be any +problems if everything is working the way it should. However, if the mount +fails for some reason, <tt>/var/video</tt> still exists, so MythTV will find +the directory and write files to it. If your <tt>/</tt> mount point is +space limited, <tt>/var/video</tt> will <bf>also</bf> be space limited, and +it won't take long to fill the partition. This will cause a number of +side-effects, most of them bad. Instead, create subdirectories as the +destination for the storage group. + +Your directory structure could then look something like this: +<tscreen><verb> +/mnt/video/drive1/video +/mnt/video/drive2/video +</verb></tscreen> + +Your <tt>/etc/fstab</tt> would look like this: +<tscreen><verb> +/dev/hdb1 /mnt/video/drive1 +/dev/hdc1 /mnt/video/drive2 +</verb></tscreen> + +Because the Storage Group path is <tt>/mnt/video/drive1/video</tt>, if the +mythbackend can only find <tt>/mnt/video/drive1</tt> it will <em>not</em> +write files to that share. + +After you create the desired directory or directories for storing your video +files, you will need to add them to the proper Storage Group using +<bf>mythtv-setup</bf>. This procedure is described below in the <ref +id="storagegroups" name="Storage Groups"> section. + +The first thing to configure is the Master backend system. If you are +running multiple backend systems, the Master backend will make all +decisions about which programs will be recorded on which tuners. If you +have only one backend, then it will be its own master. + +The Master backend will always choose the first available tuner in the same +order as you add cards through "mythtv-setup". In other words, the second +card you add will only be used when there are two overlapping recordings, +the third when there are three, and so on. +<!-- Remove the next part once .21 is released --> Therefore, you will want to have +the greatest amount of disk space on the Master backend because its tuner +will always be the first choice. You will then want to add your <ref +id="nonmaster_backend" name="other backends"> in the order of your +preference for recording. + +<figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: It is possible to <em>not</em> have the cards on the Master +backend be the first ones used. However, if you are new to MythTV it is +easier to configure the Master backend first before moving on to the Slaves, +at least until you become more familiar with the MythTV system. See <ref +id="advanced_backend_config" name="Advanced Backend Configurations"> for +information on configuring multiple backend systems in various ways. +</caption> +</figure> + +Because MythTV uses a database to store all configuration variables, +part of the bootstrap of MythTV is to indicate the location of the MySQL +database server. If the frontend, backend and MySQL database server are all +going to be running on the same box, you can continue to the next step. If +not, you'll need to change the Host Name in the "Database Configuration" +screen of the mythfrontend program. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Users that have been running the frontend and the backend on +different machines have stated that they have been having issues with remote +access to the MySQL database. The following instructions may or may not +work. Add the following to <tt>/etc/my.cnf</tt> on the backend machine and +restart MySQL. +</caption> +</figure> +<tscreen><verb> +skip-innodb +set-variable=thread_stack=256k +</verb></tscreen> + +Run the setup program: +<tscreen><verb> +$ mythtv-setup +</verb></tscreen> + +The backend setup program will start and offer you a number of choices. It +is <em>strongly</em> recommended that you go through them in order. + +The first question will ask if you wish to clear out your existing +configurations for your capture cards. Initially, you should say "YES" so +that there are no surprises later. + +The next question will ask you if you wish to clear out your video source +information. You should answer "YES" to this as well. + +Once the graphical setup starts, you'll see that there are six choices + +<figure loc="here"> +<eps file="add.eps" height="1cm"> +<img src="add.png"> +<caption> +The Storage Directories feature is available only in the SVN version of MythTV. +</caption> +</figure> + +<enum> +<item>General +<item>Capture Cards +<item>Video Sources +<item>Input connections +<item>Channel Editor +<item>Storage Directories +</enum> + +Use the arrow keys to move around, and press the space bar to select which +option you wish to configure. + +<sect2>General +<p>The first screen of the General configuration deals with IP addresses of the +system that you're running mythtv-setup on and any master backend you may have. +If you've only got one machine, then the default values are fine and you can +move to the next page by pressing the space bar. If you need to move around +the screen, use the arrow keys to move focus between settings, not the +mouse. + +If you will be deploying multiple backends, or if your backend is on one +system and you're running the frontend on another machine then <em>do +not</em> use the "127.0.0.1" IP address. + +<bf>NOTE</bf>: If you modify the 127.0.0.1 address and use a "real" IP +address, you must use real IP addresses in both fields, otherwise your +frontend machines will generate "Unexpected response to MYTH_PROTO_VERSION" +errors. + +Changing any of the port settings is very strongly discouraged. +(If you do accidentally change them, the defaults are 6543 for +the master/backend server, and 6544 for the HTTP requests) + +Once you're satisfied with the values, move the focus down to Next and hit +the space bar. + +The next screen details the Host-specific Backend setup. This is where you +will set the specific directory paths for this particular backend. Make +sure that you've followed the steps at the beginning of this section and +created a directory that exists and that MythTV will have write privileges +to. When you're done, press Next to continue, taking you to the Global +Backend Setup. + +On the Global Backend Setup configure your backend with the appropriate +settings. Use the left and right arrow keys to iterate through the choices +available on each setting, and the up and down keys to move between +settings. Move to Finish when you're done and press the space bar, taking +you back to the main configuration screen. + +<sect2>Capture Cards +<p>You should have no capture cards defined, so the highlight will be on +(New Capture Card). Press space to begin. + +Choose the appropriate settings for your particular tuner. Use the arrow +keys to move around and to make your choices, and press RETURN when +complete. Pressing RETURN will take you back to the Capture Cards screen; +if you have additional capture cards in this machine, press the space bar +when the highlight is on the (New Capture Card) row to define another card. + +If you have made a mistake, you can delete a card by highlighting it and +pressing the 'D' key, or you can highlight it and press the RETURN or 'E' +key to edit it. + +Once you have no additional cards to setup, press ESC. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +<bf>NOTE</bf>: If you have a dual digital/analog card, such as the pcHDTV +cards and some DViCO cards, then you should not configure this as two +separate cards. Configure the digital portion as a DVB card, then click +on the "Analog Options" button within the DVB configuration panel for +the card and configure the analog portion of the card there. +</caption> +</figure> + +<sect2>Video Sources <label id="VideoSources"> +<p>When you start, the highlight should be on (New Video Source). Press the +space bar to begin. The first field asks for the name of the video source. +You may choose something easy to remember, like "Antenna" or "Cable". Once +you've chosen a name, press the down arrow to move to the next field. + +If you're in North America, change the grabber to +"SchedulesDirect.org(Internal)", then continue pressing the down arrow to +move to the next field. Fill in the username (lowercase only) and password +that you have established with Schedules Direct, then move to the "Retrieve +Listings" button and press the space bar. + +<bf>NOTE</bf>: You need <bf>wget</bf> version 1.9.1 or higher to use +Schedules Direct. + +The mythtv-setup program will contact the Schedules Direct servers and get +your account information. Once you're done, you may click the Finish button +and skip the next few paragraphs in this document since they only apply to +users that are using the external XMLTV script to get their guide data. + +If you wish to continue using the XMLTV grabber, then move to the Zip/postal +code field and put in the appropriate value. + +If you're outside of North America, then some manual interaction will be +required with XMLTV. You may need to switch from the MythTV setup program +to the console it was run on to interact with XMLTV. + +Once you have chosen your provider, press RETURN to continue. XMLTV will +now begin collecting the initial data for your location. The screen may +blank for a few seconds to several minutes, depending on the load of the +listings provider and the speed of your connection to the Internet. Be +patient! + +You will then be returned to the Video Sources screen. If you have multiple +video sources available, such as Antenna, Cable, etc, go ahead and define +them all, even if they're not all going to be physically connected to the +master backend server. Once you're done, press ESC to return to the main +screen. + +<sect2>Input Connections +<p>The final configuration item is Input Connections. On this screen, you +will associate the various video sources you defined earlier with a physical +input to a encoder card. It's entirely possible that you have multiple +tuners, and each tuner has a different input, so on this screen you let +MythTV know which device will connect to which input source. + +When you start this screen, you should see a listing of the various input +connections available on each of the Capture cards you defined earlier. For +example, you may have a capture card with a tuner, a SVideo and a Composite +connection. If you wanted to associate the tuner (a.k.a., "Television") +with an "Antenna" source you defined in Video Sources, you would move to the +<tt>/dev/videodevice (Television) -> </tt> line and press the space bar. +Using the left and right arrow keys will show you the various choices you +have already created for video source. In our case, you would use the +left/right cursor keys until "Antenna" was shown in the Video Source field. +Press down to move to the next setting. + +On the connection pane there is a "Scan for channels" button, if you are +configuring a digital source such as a DVB card, you need scan for channels +and you must do this before pressing the "Fetch channels from listings +source" button. You may scan for analog channels on an analog input, but +this is not needed. + +<!-- Ugh! Who's been editing the HOWTO? This next section needs some cleanup --> + +The other button is called "Fetch channels from listings source". As long as +you have a real listings source you should fetch channels from them for +analog channels. You can do this for digital sources as well (unless the +listing source is transmitted EIT data). If you are using XMLTV, you may need +to switch from the MythTV setup program to the console it was run on to +interact with XMLTV after pressing this button. It is possible to fetch the +channels on the command line using mythfilldatabase. But if you need to do +this, you will probably need to re-enter the MythTV setup program to +configure the "Starting channel" setting for this source->input connection. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: If you have a Hauppauge PVR-500, you must think of +it has two PVR-150's on a single PCI card. For example, if you have a +single PVR-500 card, it will appear as <tt>/dev/video0</tt> and +<tt>/dev/video1</tt>. Each <tt>/dev/video</tt> device will have a Tuner input. +</caption> +</figure> +Once you're done, press RETURN to go back to the Input Connections screen. +You would then finish associating the video sources to any other hardware +devices you have available. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Don't add a video source to a hardware input if you don't +actually have anything connected there. For example, adding "Cable" to the +Tuner and to the Composite inputs without having something connected to +Composite will lead to blank recordings. +</caption> +</figure> + +Press ESC to return to the main menu, and press ESC again if you have no +further items to configure, thereby returning you to the command line. + +<sect2>Channel Editor +<p>The channel editor is used to globally alter channel information, +including items like hue, contrast, fine tuning and others. Users in North +America shouldn't run the channel editor until you've completed the initial +mythtv-setup and ran <bf>mythfilldatabase</bf> at least once to populate the +database. + +<sect2>Storage Groups <label id="storagegroups"> +<p> +<figure loc="here"> +<eps file="add.eps" height="1cm"> +<img src="add.png"> +<caption> +New in MythTV 0.21 +</caption> +</figure> +<sect3>Introduction. +<p> +Storage Groups are lists of directories that are used to hold MythTV +recording files giving you a flexible way to allow you to add capacity to +your MythTV system without having to use exotic solutions such as LVM, +filesystem expansion or RAID Online Capacity Expansion. You can also use +Storage Groups to organize recordings and to put recordings of a certain +type into one subdirectory. + +Storage Groups do not offer redundancy in case of hard drive failure, but +unlike LVM, if you lose a hard drive, you only lose the recordings that were +on that drive. With LVM, if you lose a hard drive, you will most likely +lose <bf>everything</bf>. + +<sect3>How to use Storage Groups. +<p> +By default, there is only one Storage Group called "Default", and it is +used for all recordings and Live TV. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +<bf>NOTE</bf>: You need to add at least one directory to the Default +Storage Group or else you will not be able to record anything with MythTV. +</caption> +</figure> + +For example, if you have 5 hard drives in your system, your first hard drive +could be your "boot" drive, and the remaining four could be dedicated to +media storage. You could format the drives and mount them as +<tt>/mnt/store/d2</tt>, <tt>/mnt/store/d3</tt>, <tt>/mnt/store/d4</tt> and +<tt>/mnt/store/d5</tt>. + +Within each mount point, it's <em>strongly</em> recommended that you use a +sub-directory and make that the destination path for the Storage Group. See +the <ref id="storagegrouptip" name="Tip"> in the "Configuring the Master +backend" section for additional information. + +You would then add the four subdirectories you created under the mount +points (<tt>/mnt/store/d1/video</tt>, etc) into the "Default" Storage Group. + +At recording time, if there were four simultaneous recordings, MythTV would +put one recording onto each drive. + +Or, say that you originally installed MythTV to a 80GB hard drive, and that +hard drive is now filling up. You could simply add a new drive to your +system, mount it and update the Storage Group to add additional space. + +You may create additional Storage Groups to store specific recordings in +their own directories. Storage Groups are edited via the 'Storage +Directories' section of mythtv-setup. + +You can also create multiple Storage Groups to group recordings together; +recording schedules now have an option to specify which Storage Group to +use. + +MythTV will balance concurrent recordings across the available directories +in a Storage Group in order to spread out the file I/O load. MythTV will +prefer filesystems that are local to the backend over filesystems that are +remote until the local filesystem has 2 concurrent recordings active or +other equivalent I/O, then the next recording will go to the remote +filesystem. The balancing method is based purely on I/O, Myth does not try +to balance out disk space unless a filesystem is too low on free disk space +in which case it will not be used except as a last resort. + +Storage Groups are global, but can be overridden on a slave backend by +creating a local Storage Group by running <bf>mythtv-setup</bf> on the +slave. If a problem occurs and the slave backend is unable to use the +desired Storage Group, it will fail back and try the directories defined in +the master's Storage Group. + +There's also a special 'LiveTV' Storage Group, but the directory list starts +out empty. If you add a directory to the Storage Group, it will be used +instead of putting LiveTV recordings in the Default Storage Group. This +will allow you to put your LiveTV recordings on their own filesystem, which +is similar to the old MythTV method which used a RingBuffer for LiveTV. Of +course, you don't have to do anything, and Live TV recordings will just go +into the Default Storage Group where they'll be the first programs eligible +for expiration if the system needs free space for recordings. + +Usage information for all Storage Group directories is visible on the +mythfrontend status screen as well as the mythbackend status webpage. +MythTV is smart enough to determine which directories are on shared +filesystems so it should not count free or used space multiple times if you +have more than one directory on the same filesystem. + +<sect3>Migrating to Storage Groups. +<p>Migrating to Storage groups is very simple: if you have existing +recordings in a storage directory, then the system will automatically add +that directory to the Default Storage Group. If you then add additional +directories to a storage group, the system is flexible enough to check +<em>all</em> Storage Groups for a file before deciding that it can't be +found, which means that you can use the <bf>mv</bf> command from the Unix +command line to arrange files however you'd like. + +<sect3>Advanced: Algorithm used by the Storage Group +<p>This section details the logic of the Storage Group allocation engine. + +The current load-balancing preferences (in order) are: +<itemize> +<item>Local filesystems over remote +<item>Less-busy (less weight) over more-busy (more weight) +<item>More Free Space over Less Free Space +</itemize> + +The 'business' of a filesystem is determined by weights. The following +weights are added to a filesystem if it is in use for the following things: +<itemize> +<item>recording = +10 +<item>playback = +5 (mythfrontend) +<item>comm flagging = +5 (mythcommflag) +<item>transcoding = +5 (mythtranscode) +</itemize> + +If a recording is due to end within 3 minutes, it is not counted against +the weight of a filesystem. This is done to account for the pre/post-roll +and start-early/end-late settings. + +<sect1>Post-configuration +<p>Run the <tt>mythfilldatabase</tt> program as directed. The master +backend will obtain guide data for all the video sources you defined during +setup. + +<bf>NOTE</bf>: If you are using Schedules Direct and watching the output messages +on the console or the log file it is normal to see a "401 Unauthorized" +error followed by a "200 OK" when the connection to Schedules Direct is being +established. +<tscreen><verb> +From : Sun Jun 13 05:00:00 2004 To : Mon Jun 14 05:00:00 2004 (UTC) +--02:58:01-- +http://datadirect.webservices.zap2it.com/tvlistings/xtvdService + => -' +Resolving datadirect.webservices.zap2it.com... 206.18.98.160 +Connecting to datadirect.webservices.zap2it.com[206.18.98.160]:80... +connected. +HTTP request sent, awaiting response... 401 Unauthorized +Connecting to datadirect.webservices.zap2it.com[206.18.98.160]:80... +connected. +HTTP request sent, awaiting response... 200 OK +Length: unspecified [text/xml] + + [ <=> ] 114,125 63.57K/s + +02:58:03 (63.53 KB/s) - -' saved [114125] + +Your subscription expires on 08/20/2004 12:00:00 AM +Grab complete. Actual data from Sun Jun 13 05:00:00 2004 to Mon Jun 14 +00:00:00 2004 (UTC) +</verb></tscreen> + +Once <tt>mythfilldatabase</tt> has finished, start the master server before +continuing. +<tscreen><verb> +$ mythbackend +</verb></tscreen> + +mythbackend will print information about connections and what it's doing to +the console. If you'd like to see the options that are available for +mythbackend, type <tt>mythbackend -h</tt> for help. + +As of MythTV v0.21, the available options are: +<tscreen><verb> +$ mythbackend --help +Valid options are: +-h or --help List valid command line parameters +-l or --logfile filename Writes STDERR and STDOUT messages to filename +-p or --pidfile filename Write PID of mythbackend to filename +-d or --daemon Runs mythbackend as a daemon +-v or --verbose debug-level Use '-v help' for level info +--printexpire List of auto-expire programs +--printsched Upcoming scheduled programs +--testsched Test run scheduler (ignore existing schedule) +--resched Force the scheduler to update +--nosched Do not perform any scheduling +--nojobqueue Do not start the JobQueue +--noautoexpire Do not start the AutoExpire thread +--version Version information +</verb></tscreen> + +Running mythbackend as a daemon and using the logfile option will allow you +to have mythbackend automatically start up during boot. You can follow the +steps outlined in the section called <ref id="mythbackend_autostart" +name="Automatically starting mythbackend at system boot time"> for +configuration steps. + +If you enable the <tt>-l</tt> parameter, you will want to keep your logfiles +rotated (so that they don't fill up a partition). See the section called +<ref id="logrotate" name="Automatically rotating logs"> for more +information. + +<sect1>Configuring a non-master backend <label id="nonmaster_backend"> +<p>Ensure that you've granted access to the master MySQL database for remote +backends as discussed in the section titled <ref id="modify_perm_mysql" +name="Modifying access to the MySQL database for multiple systems"> and that +you have the correct IP address for the database server in the "Database +Configuration" screen of the mythtv-setup application on this slave backend. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Slave backends <bf>must not</bf> run a local MySQL +daemon. By default, they will connect to their local daemon rather than the +central database, causing unexpected behavior such as empty "Watch +Recordings" lists and a failure to locate the Video Sources defined on the +master backend. Modify the <tt>/usr/local/share/mythtv/mysql.txt</tt> file +on all slave backends to ensure that the <tt>DBHostName</tt> has the address +of the MySQL server. + +Caveat: You may make a slave backend the primary MySQL server, or run a +non-MythTV database on a slave backend as long as you have edited the +<tt>mysql.txt</tt> file on <bf>all</bf> systems and made it consistent. +There can be only one authoritative MySQL database in a MythTV system - +errors such as the one above ensue if backends and frontends have differing +ideas of which MySQL database they should talk to. +</caption> +</figure> + +Make sure that the IP addresses on the General setup screen are accurate. +If the slave backend can't communicate with the master backend due to IP +address misconfiguration then MythTV will not function properly. + +Configuration of a non-master backend follows the same general procedure +as that of the master backend, with the exception that you skip over the +"Video Sources" step. All possible video sources need to be defined on the +master backend system; only the master backend will query a listings +provider to obtain guide data for all the non-master backends. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Do not run <tt>mythfilldatabase</tt> on a non-master backend. +</caption> +</figure> +<sect1>Configuring and running mythfilldatabase +<p><figure loc="here"> +<eps file="warning.eps" height="1cm"> +<img src="warning.png"> +<caption><bf>NOTE</bf>: <bf>mythfilldatabase</bf> might take a while to complete, +depending on any number of factors, most of which you can't control. It's +best to just let the program run to completion. +</caption> +</figure> +<bf>mythfilldatabase --help</bf> will give a full listing of the options +available. + +<bf>mythfilldatabase --manual</bf> is another option; the manual option will +allow you to fine tune channel frequencies and specify which channels will +be added to the database. + +<bf>mythfilldatabase --file</bf> is an option if there isn't an XMLTV grabber +for your country, but you <bf>do</bf> have an XML formatted listings file +created by some other program. + +<bf>mythfilldatabase --xawchannels</bf> is an option if you have used +<bf>xawtv</bf> to fine-tune your channels and would like to import the fine +tuning offsets into MythTV. + +<bf>mythfilldatabase --refresh-today</bf> will only pull guide data for +today (in case of late-breaking changes to the schedule). + +<!-- get more information on the manual setting --> + +<sect2>Periodically running <bf>mythfilldatabase</bf> +<p>In order to keep your database filled, <bf>mythfilldatabase</bf> should be +run once a day. + +To use MythTV's built-in capability, you'll need to run the +<bf>mythfrontend</bf> Setup option. From the mythfrontend, enter the +Setup>General screen and advance to "Mythfilldatabase", the fourth screen. +Select the checkbox, then complete the options as you see fit. The +<bf>mythbackend</bf> program will now run <bf>mythfilldatabase</bf> for you. + +<sect1>Grabbing channel icons for Schedules Direct users +<p>While the Schedules Direct TV listings service has several advantages, it +does not support grabbing logo icons for the stations you receive. However, +there are utilities provided with MythTV which you may use to grab your +initial set of icons and to keep them updated if your lineups change. + +First, you need to generate or obtain an XML file with the information for +your stations. + +If you have XMLTV software installed, there is a perl script in MythTV's +<tt>contrib/</tt> directory which will generate this file for you. Run the +command: +<tscreen><verb> +$ perl mkiconmap.pl +</verb></tscreen> + +You will be asked for your zip code and the service that you use. If there +are no errors, the <tt>iconmap.xml</tt> file that you need for the next step +will be created. + +If you do not have XMLTV software installed and do not want to install it +for the sake of this minor task, there is a generic +<tt>contrib/master_iconmap.xml</tt> which you can copy and use but this may +not be as complete as using the specific information for your service. + +Once you have an <tt>iconmap.xml</tt> file, add the icon information to your +database and grab any new icons with the command: +<tscreen><verb> +$ mythfilldatabase --import-icon-map iconmap.xml --update-icon-map +</verb></tscreen> + +<sect>Configuring mythfrontend. +<p>Once you have completed configuration of your backend systems, the next +step is to configure the frontend client. + +When you start mythfrontend for the first time, it will attempt to connect +to a configuration database on the local machine. If there is none, a +"Database Configuration" screen will appear, and you will need to fill in +some details. The "Host name" field needs the backend or database server's +IP address or DNS name, and the User or password fields may need to be set +to match your database user accounts. After editing those fields, press +Enter twice to write these configurations on your local machine, and attempt +to connect to the database. If you make any mistakes, the screens will pop +up again. + +Now that mythfrontend has started up, you should have a number of +buttons/choices. Before doing anything, go to TV, then to Setup and +configure the frontend client. +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: You should go through the various setup screens in +mythfrontend before using any other modules to ensure that the the database +is correctly initialized. +</caption> +</figure> +<sect1>General +<p>The General screen has configuration items that don't really fit anywhere +else. The first few configuration items ask you to indicate the number of +seconds to record before or after a program, which is useful if the +broadcast network or your system clock are out of sync and will help prevent +you missing the beginning or end of a program. + +To change the value, use the left and right arrow keys to increment and +decrement the number of seconds. When you're satisfied with the result, use +the down arrow to put the input focus on the Next button or press RETURN to +continue to the next page. + +The next page has a number of options to do with how channels are displayed +on your system. The help text will give you more information. Move the +focus to Next and press the space bar to continue. + +The last General page sets up some final configuration items. See the help +text for more information. + +<sect1>Appearance +<p>This set of screens is mostly concerned with how MythTV will look on your +system. From here, you can choose different themes and set the resolution +of your system. + +<sect1>Program Guide +<p>Fairly self explanatory. Note that the alternate program guide does not +use the same font settings as defined in Appearance, so if the EPG is +unreadable this is where you make the adjustments to fonts, number of +elements displayed, etc. + +<sect1>Playback <label id="deinterlace_"> +<p>The one configuration item which may cause problems on your system is the +"Deinterlace playback" setting. MythTV uses a linear blend algorithm for +deinterlacing, which will improve how the image looks on your screen. +Deinterlacing requires that your processor support SSE. (Streaming SIMD +Extensions, aka "MMX2"). Early Intel Celeron (those that don't use the +Coppermine 0.18um core and are usually <600MHz), Pentium Pro and Pentium II +CPUs do not have SSE, so make sure you haven't enabled deinterlacing if +your processor doesn't support it. If you enable it, and your processor +doesn't support SSE, you will get "Illegal Instruction" errors. + +To determine if you've got SSE on an Intel processor, you can: +<tscreen><verb> +$ cat /proc/cpuinfo +[snip] +flags : fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca +cmov pat pse36 mmx fxsr sse +</verb></tscreen> + +Notice the <bf>sse</bf> at the end of the line - this tells you that this +processor will be able to deinterlace correctly. + +On an AMD processor, look for "3dnow" in the cpuinfo line; "3dnow" is AMD's +implementation of SSE instructions, so if your processor has 3dnow you +shouldn't have any issues with deinterlacing. +<sect2>Video Filters +<!-- Submitted by Bruce Markey --> +<p>MythTV provides a means of employing video filters while recording and +during playback. These filters can be used to improve or modify the video +image, including hiding the effects of an interlaced image or reducing the +impact of noise in a poor video signal. The following is a brief +introduction to introduce you to the filters that are available in MythTV +version 0.20 and higher. +<sect2>Applying filters +<p>One or more filters can be included in a "filter chain". The filters to +be used are identified in a "filter string". A filter string is a group of +filter names and parameters separated by commas. To include parameters, the +filter name is followed by "=" and the parameter information. There should +be no spaces in the filter string. Here is an example filter string: + +With parameters: <tt>kerneldeint=10:1,denoise3d=12</tt> + +Without: <tt>kerneldeint,denoise3d</tt> + +Recording filters are set for each individual channel. These may be used +when encoding in software (MPEG-4, RTjpeg) but do not apply when using a +capture card with hardware encoding such as those supported by the ivtv +driver, DVB, HDTV or MJPEG cards. You can run MythTV's "setup" program and +select the "Channel Editor". On the first page for each channel, you can +enter a filter string in the box titled "Video filters". If you are running +"mythweb" on your web server, you can click on "Settings" then "Channels" +and enter filter strings in the "videofilters" column. + +Playback filters are per-host and apply to any recording you watch from the +frontend where filters have been applied. Playback filtering can only +work with software decoding so the viaslice, xvmc, and ivtv outputs ignore +filters entirely. From "mythfrontend" go to Setup->TV Settings->Playback. +Enter your filter string in the box titled "Custom Filters". + +<sect2>Currently Available Filters +<p>"Deinterlace Playback" checkbox. + +This implements special behavior needed for the "bobdeint" filter but can +also be used to choose any of the deinterlace filters. If you prefer, you +may leave this unchecked and include any of the deinterlace filters, other +than "bobdeint", in your custom filter chain. + +o The "invert" filter + +Invert ignores any parameters and inverts the pixel values of the video +frames. In other words, a negative image. This would rarely be useful but +may be a good example to verify that your filter strings take effect. + +o The "linearblend" filter + +It is a simple deinterlacing filter that ignores parameters and works by +blending adjacent lines. It replaces combing in interlaced video with a +less distracting "ghost" image. + +o The "bobdeint" filter + +This filter splits the interlaced image into two separate fields that +can be line doubled then displayed at twice the frame rate. If the +display is at the same refresh rate as the recording (59.92Hz NTSC or +50Hz PAL) this will cause each refresh to show objects in motion in +a new position with no jagged edges. However, if the display is not +synchronous, it will cause flickering or the appearance of the picture +moving up and down by one line. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: This filter requires the frame rate to be doubled +and therefore can only be used with the "Deinterlace Playback" checkbox. +Do not include this in your filter chain. +</caption> +</figure> + +o The "kerneldeint" filter + +Kerneldeint is a more complex deinterlacing filter which applies a filter +kernel using input from several lines. It generally removes combing without +a "ghost" image, sometimes leaving a faint outline of the image from the +other field. It is considered to be less distracting to watch than +linearblend or no filter at all. It accepts one or two integer parameters +separated by a colon. + +The first parameter is the filter threshold and defaults to 12. Adjacent +lines differing by more than the threshold value are filtered. The second +option defaults to 0. If set to a non-zero value, it will cause the filter +to skip chroma, and filter only the luminance. It may be useful on some +capture cards which do not capture the chroma fields of interlaced video +correctly. + +o The "onefield" filter + +This is a simple one-field deinterlacing filter that uses only one field of +the interlaced video. By default it keeps the top field, though passing the +parameter "bottom" will cause it to keep the bottom field instead. + +This filter is primarily useful for those who display 1080i HDTV signals +with a video mode that has 540 pixels vertically. The advantage over other +deinterlacing filters is that scenes with motion never show combing or +ghosting. + +o The "adjust" filter + +This filter adjusts the digital values for luma and chroma to ensure that +they will fall within the ranges specified in the ITU-R601 standard. By +default, this corrects a known problem for the luma range used by bt8x8 +chips which causes video to look washed out. If parameters are passed, there +need to be exactly six. However, passing a single parameter of "-1" will +disable the filter. + +1: luma minimum input value (int) +2: luma maximum input value (int) +3: luma gamma correction (float) +4: chroma minimum input value (int) +5: chroma maximum input value (int) +6: chroma gamma correction (float) + +The default bt8x8 correction values are equivalent to +"16:253:1.0:2:253:1.0". Output ranges are fixed at ITU-R601 values (16-235 +luma, 16-240 chroma). + +<bf>NOTE</bf>: If it is not already specified in the filter chain, this +filter will be automatically applied when recording with the "bttv" driver. + +o The "quickdnr" filter + +A fast temporal denoiser. This can take 1, 2 or 4 parameters, each being a +value from "0" for the least filtering to "255" for the greatest filtering. +With one parameter, the filter will compute the values it should use for all +of its variables. Two parameters will set the filter strength for luma and +chroma independently. If you are interested in how the algorithm works, you +may examine the source code to see how four parameter are used. + +o The "denoise3d" filter + +A slower denoiser that applies a spatial and temporal low-pass filter. The +spatial filter can remove some noise that quickdnr can't, but a more +powerful CPU is needed. This filter accepts 3 float parameters: + +<itemize> +<item>luma spatial filter strength +<item>chroma spatial filter strength +<item>luma temporal filter strength +</itemize> + +Reasonable defaults will be selected for omitted parameters. The chroma +temporal filter strength is calculated from the other filter strengths. + +o The "crop" filter + +Covers edges of video with black bars. This helps improve video quality +when the edges of the frame are distorted. By default, this removes 16 +pixels from each edge. This can optionally take four parameters representing +top:left:bottom:right. The number times 16 is the number of pixels to remove +so, for example, the default is "=1:1:1:1". + +o The "forceyv12" and "forceyuv422p" filters + +These force the filter manager to use the given format. You can use one of +these at the head of a filter chain to change the capture format. The most +likely use would be forceyuv422p to use YUV422P capture on cards with known +chroma interlacing problems with YV12. + +There are some filters included in the MythTV source code that should +not be used: + +o The "forcergb24" and "forceargb32" filters + +The two RGB formats should not be used because there is no conversion filter +for them yet. + +o The "convert" filter + +It exists but don't use it. The filter manager uses this filter +automatically when it is unable to match the input/output formats of two +adjacent filters. + +o The "postprocess" filter + +While this exists in MythTV source code, it is currently not recommended for +use. + +<sect2>Usage Considerations +<p>There are trade-offs to consider when deciding if it would be wise to use +a filter. Any processing will modify the original image so you should assess +if the filter has made a noticeable improvement to the picture in order to +justify the impact of the processing. Adding any filter will inherently +increase CPU usage. The impact can vary dramatically depending on your CPU +type and speed, the resolution of the recording, which filters you are using +and other factors. You can only determine what is right for you through +experimentation. However, as a starting point, here are some filter strings +that you may find useful: + +For typical broadcast stations: "kerneldeint,quickdnr" + +For stations with poor signal quality: "linearblend,denoise3d=12" + +For synchronous TV-out: check Deinterlace with "Bob (2x framerate)" + +<sect1>Recording <label id="Recording"> +<p>Depending on your capture card, MythTV offers different video encoders. +The following types of hardware encoding cards are supported: +<itemize> +<item>MJPEG - Zoran-based cards; see <url url="http://mjpeg.sourceforge.net" name="http://mjpeg.sourceforge.net"> +<item>MPEG-2 - iTVC15/16 based cards (Hauppauge PVR-250/PVR-350); see <url +url="http://ivtvdriver.org" name="http://ivtvdriver.org"> +<item>HDTV - pcHDTV cards; see <url url="http://pchdtv.com" name="http://pchdtv.com"> and +the Air2PC-ATSC-PCI see <url +url="http://www.cyberestore.com/product_info.php?cPath=28&products_id=103" +name="http://www.cyberestore.com/product_info.php?cPath=28&products_id=103"> +<item>DVB - cards supporting DVB; see <url url="http://linuxtv.org" name="http://linuxtv.org"> +</itemize> +For cards without hardware encoding capabilities (all cards supported by +V4L not listed above), Myth includes two methods for software encoding: +RTjpeg and MPEG-4. RTjpeg has significantly fewer CPU demands than MPEG-4, +but it generates larger files than MPEG-4 for a given recording. + +For DVB and HDTV cards, no further configuration is required after +setting up the card using the 'mythtv-setup' program. +For all other cards, configuration is done through MythFrontend. +Selecting 'Recording Profiles' from the 'TV Settings' screen will list +the profiles currently available for the cards in your system. +Depending on what types of cards you have installed you may see: +<tscreen><verb> +(Create new profile group) +Software Encoders +Hardware MPEG Encoders +Hardware MJPEG Encoders +Transcoders +</verb></tscreen> +The '(Create new profile group)' option will allow you to create custom +profiles in case you have multiple backends. Note that custom profiles +are per backend and card type. If you have 2 MPEG-2 encoders in a given +backend system, creating a custom profile will affect both of them. This +option should not be needed otherwise. + +The 'Transcoders' group is a little different from the others. Selecting +this group will result in a menu with the following options: 'RTjpeg/MPEG-4' +and 'MPEG-2'. These types indicate what transcoder options will be used for +a given input type (i.e. the 'MPEG-2' settings would be used to transcode +MPEG-2 files into MPEG-4. The source of the MPEG-2 stream (DVB, HDTV, or +PVR-x50) does not matter. Configuration of the options is the same as below +(although any resolution settings will be ignored). + +Selecting any of the other options will show a new screen with a list of +four profiles: +<itemize> +<item>Default +<item>Live TV +<item>Low Quality +<item>High Quality +</itemize> + +The Default profile will be used for any recording which does not otherwise +have a specific profile assigned. The 'Live TV' profile will be used when +watching TV. The remaining two profiles are available for customizing to +allow for more precise control over what quality is used for a given +program. + +Selecting a profile will allow you to adjust the relevant options for that +card. The most significant setting is the recording resolution, but you can +also choose encoding format, audio format, and tweak other encoder specific +properties. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: although the width and height can be changed to almost +anything, if you start MythTV and don't see video or you get "segmentation +fault" errors, it is likely that the video4linux (v4l) subsystem did not +like the height and width parameters specified. It's best to leave the +default as-is until you're sure that MythTV is operational. +</caption> +</figure> + +See the <ref id="capture_resolution_" name="What capture resolution should I +use? How does video work?"> section for more information. + +<sect1>Xbox Frontends +<p>MythTV is able to control the LED on the Xbox to indicate backend +recording status. + +To control the LED, you will need the <bf>blink</bf> program from the +xbox-linux project, which is installed as <tt>/bin/led</tt> on GentooX. On +Xebian (the new Ed's Debian) you must install it yourself. On other +distributions it may or may not be installed as a program called +<bf>blink</bf> and should be located in your path. (Type <tt>which +blink</tt> to see if the program is available.) If you do not have +<bf>blink</bf>, you may obtain it from the Xbox-Linux project site at <url +url="http://xbox-linux.sf.net/" name="http://xbox-linux.sf.net/">. The +program you need is part of the <tt>eds_i2c_staff</tt> module in CVS. Note +the spelling. + +Once you have installed <bf>blink</bf> you will need to set permissions. +<bf>blink</bf> needs write permission to the i2c device to function +properly. There are three methods to accomplish this. First, you could run +<tt>mythfrontend</tt> as root, which is the simplest method, but could +potentially be a security risk. Next, you may make the <bf>blink</bf> +binary setuid root, which allows non-privileged users to run a program with +root capability. This is done by typing the command: +<tscreen><verb> +$ su +# chmod u+s /path/to/blink +</verb></tscreen> +The final technique would be to set the <tt>/dev/i2c/0</tt> device read/write +for all users, but this is the least preferred method. + +Now it's time to setup MythTV for Xbox hardware. Enter Setup -> General. +On the second page check the 'Enable Xbox Hardware' option. Upon reentering +the settings, you should have a new option named 'Xbox'. Within this option +you may select the distribution, LED colors for recording and the update +interval. If you select GentooX as the distribution <bf>led</bf> will be +used as the <bf>blink</bf> binary name, otherwise, <bf>blink</bf> is used. +Colors should be self explanatory. The update interval determines how often +the frontend should poll the backend to determine if the status has changed. + +<sect>Using MythTV. +<p><figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +<bf>NOTE to Red Hat/Fedora 4 users</bf>: Red Hat Linux and Fedora Core ship +with Gnome as the default desktop environment. However, Gnome seems to have +issues with window focus and window switching which sometimes cause +mythfrontend to obscure the video. KDE does not seem to have any such +issues. Therefore you will need to switch to KDE by selecting +RedHatMenu>Extras>System Settings>Desktop Switching Tool and choose "KDE". + +<bf>NOTE to Fedora Core 5 and 6 users</bf>: Fedora 5 and 6 no longer have +this tool in the Menu. Use "switchdesk KDE" from a command line. Read "man +switchdesk" for further information about changing to other desktop +environments. +</caption></figure> +<sect1>Keyboard commands +<p>The <tt>keys.txt</tt> file describes what the various keyboard commands are. +If you have loaded mythweb, you may change the default keys to your liking. +<sect2>mythfrontend +<p> +<table loc=p> +<tabular ca="rll"> +Arrow keys | used to move the highlight point around @ +ALT-F4 | exit out of the application @ +Space/Enter | take action on the item under the highlight point @ +P | play in both "Watch a Recording" and "Delete a Recording" @ +D | delete in both "Watch a Recording" and "Delete a Recording" @ +U | to view details for the currently selected show on the Watch + or Delete screens, EPG, "Program Finder", "Fix Scheduling + Conflicts" and search results screens @ +O | to list the upcoming episodes for the currently selected show + on the EPG, "Program Finder", "Program Recording Priorities", + "Fix Scheduling Conflicts" or search results screens @ +I | edit recording options from the EPG, "Program Finder", + "Program Recording Priorities", or "Fix Scheduling Conflicts" + screens. From the Playback and Delete screens, 'I' presents + options for recorded shows such as Auto Expire or Stop Recording. + Pressing 'I' while on the Recording Options screen will take you + to the Advanced Recording Options screen. +</tabular> +</table> +<sect2>Watching TV or a recording +<p> +<table loc=p> +<tabular ca="rll"> +Up or down | keys change the channel @ +num pad | Type a number to enter a channel number or jump amount (HHMM format) @ +P | pause / play. You may also add an explicit keybinding for 'Play' through + MythWeb, returning you to normal speed if you are in slow motion, rewind + fast forward or pause mode. @ +C | change inputs on TV Tuner card @ +ESC | quits @ +I | puts the On-screen Display up again. During playback, 'I' toggles + between position and show description info. If a jump amount is + entered, jump to that position. @ +M | brings up the electronic program guide (Grid) -- see the EPG section @ +Page Up | jump back the configured number of minutes (default is 10) @ +Page Down | jump ahead the configured number of minutes (default is 10) @ +End or Z | skip to next commercial break marker @ +Home or Q | skip back to previous commercial break marker @ +T | toggle close caption support + Pressing 0-9 (preferably 3 times) + T changes teletext page and turns on teletext. @ +F | rotate between the various Picture Adjustments (Colour, Hue, etc.) + While Picture Adjustment is on-screen, use Left and Right arrows to + adjust. These settings adjust the look of the video playback, and are + independent of the G-key settings used at record-time. @ +[ or F10 | decrease volume @ +] or F11 | increase volume @ +| or F9 | toggle mute @ +/ | jump to the next "favorite" channel @ +? | mark/unmark the current channel as a "favorite" @ +U | increase the play speed @ +J | decrease the play speed @ +A | Adjust time stretch (speed up or slow down normal play of audio and video @ +W | cycle through zoom and fill modes: 4:3 aspect ratio, 16:9, 4:3 Zoom + (like Pan and Scan), 16:9 Zoom, and 16:9 Stretch (eliminates black + sidebars in TV signal) @ +F8 | toggle the sleep timer 30m->1hr->1hr30m->2hr->Off @ +CTRL-B | Jump to the beginning of the recording / ringbuffer @ ++ | Switch between audio streams @ +Left | (if a jump amount is entered) to jump back that amount @ +Right | (if a jump amount is entered) to jump ahead that amount @ + | @ + | @ + | <bf>Without the stickykeys option selected</bf> @ +Left | rewind the configured number of seconds (default is 5) @ +Right | fast forward the configured number of seconds (default is 30) @ +< | starts rewind mode as if stickykeys are selected @ +> | starts fast forward mode as if stickykeys are selected @ + | @ + | @ + | <BF>With Stickykeys option selected</BF> @ +Right | starts fast forward mode @ +Left | starts rewind mode @ + | @ + | @ + | <bf>In fast forward or rewind mode:</bf> @ +Left/Right | increases the ff/rew speed @ +0 | plays at normal speed, but leaves the time indicator on screen @ +1 or 2 | plays back more slowly than normal ff/rew speed (1 is slowest) @ +3 | plays back at normal ff/rew speed @ +4-9 | plays back faster than normal ff/rew speed (9 is fastest) @ +Space | exits fast forward or rewind mode @ + | @ + | @ + | <bf>While video is paused:</bf> @ +Left | rewind 1 frame @ +< | rewind 1 second @ +Right | advance 1 frame @ +> | advance 1 second +</tabular> +</table> +<sect2>Watching TV only +<p> +<table loc=p> +<tabular ca="rll"> +G | rotate between the various Picture Adjustments (Colour, Hue, etc.) + for recording. These values affect the look of the resulting .nuv + file, and are independent of the playback picture settings. While + Picture Adjustment is on-screen, use Left and Right arrows to adjust. @ +H | Channel history. Each repeat steps back through the previous channels. @ +O | Turns on 'Browse' mode, allowing user to browse channels and program + info while watching current show FullScreen. @ +Y | switch between multiple capture cards. <bf>NOTE</bf>: + you will lose your LiveTV buffer on your current card. Useful + for different-sourced cards (such as Dish Network on one, HDTV over-the-air on another card.) @ +</tabular> +</table> +<sect2>LiveTV Browse Mode +<p> +<table loc=p> +<tabular ca="rll"> +Left | browse program prior to current listed program @ +Right | browse program following current listed program @ +Up | browse program on channel above current listed channel/program @ +Down | browse program on channel below current listed channel/program @ +/ | browse program on next favorite channel @ +0-9 | enter a channel number to browse @ +Space/Enter | change channel to channel of current listed program @ +R/r | Toggle recording of current program (cycles through types) @ +ESC/O | Exit Browse mode +</tabular> +</table> +<sect2>Playback Recording Zoom Mode +<p> +<table loc=p> +<tabular ca="rll"> +Left | Move video to Left @ +Right | Move video to Right @ +Up | Move video Up @ +Down | Move video Down @ +PageUp | Zoom In @ +PageDown | Zoom Out @ +Space/Enter | Exit Zoom mode leaving picture at current size and position @ +ESC | Exit Zoom mode and return to original size +</tabular> +</table> +<sect2>If you have two or more tuner cards +<p> +<table loc=p> +<tabular ca="rll"> +V | toggle Picture-in-picture on or off @ +B | toggles the window focus (lets you change channels on the PiP window) @ +N | swaps the two channels by changing channels on both cards +</tabular> +</table> +<sect2>Watching a recording only +<p> +<table loc=p> +<tabular ca="rll"> +Space/Enter | set a bookmark at that point. Next time you start the + recording, you will automatically jump forward to this point + and clear the bookmark. @ +X | queues the current recording for transcoding @ +O | brings up menu to allow toggling settings such as Commercial + Auto-Skip, Auto-Expire, etc. @ +D | exits the current recording and displays the Delete menu @ +E or M | enters/exits edit mode. @ + | @ + | @ + | <bf>In edit mode</bf> @ +Left/Right | move forward and backward @ +Up/Down | alter the amount of time you jump forward and backward. + Increments are: nearest cutpoint, nearest video keyframe, 1 + frame, 0.5 seconds, 1 second, 20 seconds, 1 minute, 5 minutes, + and 10 minutes. @ +PageUp/PageDown | move forward and backward to the nearest cut point @ +< or > | move forward or backward by 10 times the normal jump amount @ +Space/Enter | allows you to set or delete a cut point @ +Z | loads the commercial skip list (if one exists) into the cutlist @ +C or Q | clear all cut points in the cutlist @ +I | Inverts the cutlist +</tabular> +</table> +<sect2>EPG +<p> +<table loc=p> +<tabular ca="rll"> +Arrows | are used to move the highlighted program point around @ +A, D, S, W | perform the same as left, right, down and up @ +PageUp/PageDown | move the channel list up or down a page @ +Home/End | move the highlight left or right by one day @ +Ctrl+Left or < | move the highlight left by one page @ +Ctrl+Right or > | move the highlight right by one page @ +9, 3, 7, 1 | (like a numeric keypad) perform the same as PageUp, PageDown, + Home and End @ +I | bring up more information about a show, and allow you to + schedule a recording. If you select "Record this showing" + while watching Live TV you can "Instant Record" a program. @ +Space/Enter | allow you resolve conflicts or change overrides. If the + program is not already scheduled to record, it will instead act like + pressing 'I'. @ +M | when on a channel will change to that channel @ +ESC or C | exits without changing the channel @ +R | change the current item from Recording/Not-Recording. + Successive keypresses cycle through the scheduled recording + type list. @ +X | change the channel to the currently selected channel without + leaving the EPG (Most useful in the alternate EPG) @ +? | mark/unmark the current channel as a "favorite" @ +/ or 4 | toggle the guide listing between all channels and filtered + "favorites" +</tabular> +</table> +<sect2>Setting Program or Channel Recording Priorities +<p> +<table loc="l"> +<tabular ca="rll"> +Right | increases priority value @ +Left | decreases priority value @ +1 | sorts by title @ +2 | sorts by priority @ +Home/End | toggle sort priority @ +I | edit recording options @ +ESC | commits changes and exits +</tabular> +</table> +<sect2>Viewing Scheduled Recordings/Resolving Conflicts +<p> +<table loc=p> +<tabular ca="rll"> +1 | show all recordings @ +2 | show only important recordings @ +Home/End | toggle show showing all/important @ +I | edit recording options @ +Space/Enter | resolve conflict or override +</tabular> +</table> +<sect2>Viewing Search Listings +<p> +<table loc=p> +<tabular ca="rll"> +Home | change to the previous view if applicable @ +End | change to the next view if applicable @ +M | select another view if applicable. In the + title and description search popup, press + M again to edit or delete the selected view. +</tabular> +</table> +<sect2>Recording Profiles Setup Screen +<p> +<table loc=p> +<tabular ca="rll"> +D | on a custom profile group displays a popup to delete the group@ +</tabular> +</table> +<sect2>Recording Groups +<p>In the Watch Recordings screen, Recording Groups allow you to separate +programs into user-defined categories, such as "Kids", "Alice", "Bob", etc. +This can be used to reduce clutter, or to segregate content if you use the +PIN function. +<table loc=p> +<tabular ca="rll"> +M | change the view or to set a group password @ +I | move a program from one Recording Group to another +</tabular> +</table> +<sect2>Watch Recordings Screen +<p> +<table loc=p> +<tabular ca="rll"> +1 or F1 | Meaning of the icons @ +/ | Tags a recording. Tagged recordings can be played + either in order or shuffled and deleted as a group. + You can also change the recording group for several + recordings at once by tagging them and using the + Menu (m) button, selecting "Playlist options", + then "Change Recording Group". @ +? | Clear the tagged list. +</tabular> +</table> +<sect2>Remote Controls +<p> +If you are using MythTV with just a remote control then it is suggested that you +map the remote control keys as described below. Your remote control may not +have the same set of keys as those named below, the names are only a suggestion +that roughly correspond to the function. +<p> +If you are adding new key bindings to the program then consideration of this +suggested list will help users with remote controls. +<p> +This list assumes a minimal remote control that only has 20 keys, nearly all +features can be used with this configuration. If you have more keys then you +can access all of the features. With only 16 keys most features are usable. +<table loc=p> +<tabular ca="rll"> +REMOTE CONTROL | LIRC KEYSTROKE | FUNCTION @ +0 - 9 | 0 - 9 | channel selection, EPG navigation, ff/rew speed setting (with stickykeys) @ +Left Arrow | Left | scroll left, rewind @ +Right Arrow | Right | scroll right, fast forward @ +Up Arrow | Up | scroll up, channel change up @ +Down Arrow | Down | scroll down, channel change down @ +Select / OK / Play | Space | Select item, play (with stickykeys) set bookmark @ +Cancel | Escape | Cancel, quit playback @ +Menu | m | EPG (from watching TV) edit (from playback). @ +Pause | p | Pause @ +Other key 1 | i | Information @ +Other key 2 | c | Change tuner card input +</tabular> +</table> + +<sect1>Using themes with MythTV +<p>MythTV is "themeable", meaning that the visual appearance of the program +can be modified by the user without re-compiling or altering the program +functionality. Download the MythThemes tarball from the website and untar it: + +<tscreen><verb> +$ tar -xjf myththemes-0.21.tar.bz2 +$ cd ~/myththemes-0.21 +$ qmake myththemes.pro +$ su - +# make install +# exit +$ +</verb</tscreen> + +The theme will now be available in the mythfrontend Appearance section. + +<sect1>Adding DishTV information to the database +<p>A script for adding Pay Per View information into the MythTV database for +DishTV subscribers is available at <url url="http://www.mythppv.com/" +name="http://www.mythppv.com/">. + +<sect1>Adding support for an external tuner +<p>MythTV supports changing the channel on an external tuner. If you have +an external tuner, such as a DirecTV or digital cable set top box, you +should add <tt>/usr/local/bin/changechannel</tt> to your Input Connections in the +mythbackend configuration GUI. + +However, there is not <bf>changechannel</bf> program per-se, because this is +going to be dependent on what sort of external tuner you have. Look in the +<tt>contrib/channel_changers</tt> directory for a number of programs and +scripts which may be used to change channels. Once you find one which +works, copy it to <tt>/usr/local/bin/changechannel</tt>. + +Feel free to browse some of what sort of hardware is available at <url +url="http://store.snapstream.com/accessories.html" +name="http://store.snapstream.com/accessories.html">, or if you wish to +assemble your own, rather than purchase, the following may be helpful: <url +url="http://www.dtvcontrol.com/" name="http://www.dtvcontrol.com/"> for +cable pinouts. + +<sect1>Using Shutdown/Wakeup +<p>What does the MythTV Shutdown/Wakeup function do? The scheduler on the +Master backend (MBE) keeps track of the idle status of the entire MythTV +system, including the Slave backends (SBE). If it considers the system to be +idle, and thus ready to shutdown, it sets the wakeuptime to the time of the +next recording and then proceeds to shut down all Slave backends and then +itself. Once it is time to begin recording, the Master backend and the Slave +Backends are automatically woken up. This system allows MythTV to record +like a normal VCR, thereby conserving power when not in active use. + +In order to use the Shutdown/Wakeup function there must be some method of +waking up the Master backend. There are any number of solutions, but we +will discuss in detail two possibilities: + +<itemize> +<item>Use another server that runs 24/7 and have it send a WakeOnLAN (WOL) +packet to wake the Master backend. This assumes that you have the WOL tools +installed, and that your Master backend motherboard supports WOL. +<item>Use your motherboard's BIOS wakeup capability. You'll need a motherboard +that supports BIOS wakeup, and some tools. Two that work are: <url +url="http://sourceforge.net/projects/nvram-wakeup" +name="http://sourceforge.net/projects/nvram-wakeup"> and <url +url="http://www.malloc.de/tools/wakeup_clock.html" +name="http://www.malloc.de/tools/wakeup_clock.html"> +</itemize> + +<sect2>A deeper look into the operation +<p>The scheduler keeps track of the idle status of the MythTV system. To +determine whether or not the MythTV system is idle, the following conditions +must be met for a period of time defined in the "Idle timeout (secs)" +parameter. +<itemize> +<item>no client is connected to the server +<item>no recording (neither LiveTV nor a regular recording) is currently taking place +<item>no recording starts within a definable amount of time ("Max. wait for recording (min)") +<item>the "pre Shutdown check-command" returns 0 +</itemize> + +If we get to this idle state the Master backend will set the wakeuptime using the "Set +wakeuptime command", which is the same for WOL and BIOS wakeup. The Master backend will +then shut down the Slave backends and itself using the "Server halt command". + +One caveat is that the scheduler tries to guess if the Master backend was started by a +wakeup call or by the user. If it thinks it was woken up by a user, it +blocks shutdown until a client connects to the Master backend, after which it will +behave as described above. To disable this feature, unset "Block shutdown +before client connected" in the mythfrontend Setup->Setup->General screen. + +Once it is time to startup the system, the Master backend is woken up first and will +wakeup the Slave backends using the "Wake command for slaves". At this time, there is +no support for starting only the required Slave backend, so all Slave backends will startup. + +<sect2>Setting up the MythTV side of this extension. +<p>There are a number of options that are used to control the Shutdown / +Wakeup feature. + +Shutdown/Wakeup Options: +<itemize> +<item>"Idle timeout (secs)" is the time the server waits while idle until a +shutdown occurs. +<item>"Max. wait for recording (min)" is the time the Master backend waits for a recording +without shutting down. For example, this would be used to prevent a 10 +minute system shutdown if a recording is set to start 15 minutes from now. +<item>"Startup before rec. (secs)" Sets how long before a programmed +recording the MythTV system will be woken up. This should be roughly be the +time your systems need to bootup, and if you have Slave backends, you'll +need to ensure this value is long enough for all your machines to perform +their bootup cycle. +<item>"Wakeup time format" is the format of the wakeup time that is given in +the "Set wakeuptime command" as a parameter "$time". You need to set this +according to your wakeup mechanism. If you need seconds since the epoch +(1970-01-01) set the "Wakeup time format" to "time_t". +<item>"Set wakeuptime command" is the command executed to set the new wakeuptime. +<item>"Server Halt Command" is the command executed to shutdown the Master +backend and the Slave backends. +<item>"pre Shutdown check-command" is used to give a +"Go/NO-GO" decision from a non-MythTV source. This command is executed +immediately before the shutdown would occur. The return value is use to make +the following choices: +<itemize> +<item>If it returns a "0" the shutdown will occur as scheduled. +<item>If it returns a "1" the "idle timeout" will be reset and the system +waits again for the timeout. +<item>If it returns a "2" the entire shutdown sequence is reset. This means +that a new client connect is needed before a shutdown occurs, unless you have +the "Wait for client connect" setting disabled, in which case this is the same as +returning "1". An example of a use for this return value is to prevent the shutdown +if a user is currently logged in, or if a specific program (i.e. transcode, +automatic updates, etc.) is currently running. If you don't need it, leave +the field blank. +</itemize> +</itemize> + +The "WakeOnLan settings": +These settings have nothing to do with using BIOS or WOL wakeup, they are +the same for both. +<itemize> +<item>"Master backend" This setting defines timings for the frontends to +wakeup the Master backend using WOL. Useful if your frontend can emit a WOL +packet so you don't need to physically go to the Master backend if you're +trying to watch TV. +<item>"Reconnect wait time (secs)" is the time the frontend waits after +executing the "Wake command" before attempting to retry the connection. This +should be roughly the amount of time your Master backend needs for bootup. +Set to "0" to disable. The frontends will retry to connect for "Count of +reconnect tries" times before giving up. +<item>"Wake command for slaves" is the <em>one</em> command executed to wake +your Slave backends. This should be a script that contains the calls to +wakeup all Slave backend systems. +</itemize> + +<sect3>Using WOL to wake your Master backend. +<p>To use WOL to wake your Master backend you will need a WOL capable Master +backend, a machine that runs 24/7 which can execute an at-job and nc (netcat) +on the Master backend. I use some little bash scripts to make my DSL router +wakeup my mythbox if required. + +Replace $SERVER and $PORT with your own settings! +On my Master backend I have a script that gets called as 'setwakeuptime command' which +looks like the following: +<tscreen><verb> +#! /bin/sh +echo $@ | nc $SERVER $PORT +</verb></tscreen> +This simply cats the parameters (that is $time) to my 24/7 server. On my +$SERVER I have (x)inetd listening on $PORT starting a little script which +cares about setting the at-job. The following additions are necessary on the +$SERVER: + +If you use <bf>inetd</bf>: +<p>In <tt>/etc/inetd.conf</tt> add: +<tscreen><verb> +mythwake stream tcp nowait mythtv /usr/sbin/tcpd /usr/local/bin/mythwake +</verb></tscreen> +If you use <bf>xinetd</bf>, save the following as <bf>mythwake</bf> in your +<tt>/etc/xinet.d/</tt> directory: +<tscreen><verb> +service mythwake + { + socket_type = stream + wait = no + user = mythtv + protocol = tcp + id = mythwake + server = /usr/local/bin/mythwake + } +</verb></tscreen> +and add the following to <tt>/etc/services</tt>: +<tscreen><verb> +mythwake $PORT/tcp +</verb></tscreen> + +Finally, <tt>/usr/local/bin/mythwake</tt> looks like: +<tscreen><verb> +#! /bin/bash +#this should be a command to wake your server +WAKECMD="#!/bin/sh\n /usr/local/bin/wakeMBE" +#first we need to delete all wake jobs in queue +for JOB in atq | cut -f 1 ; do + atrm $JOB; +done +#now we read the date from 'nc' +read date; +#now set the atjob +echo -e "$WAKECMD" | at $date ; +</verb></tscreen> +<bf>SECURITY WARNING</bf>: +Be sure to secure $SERVER:$PORT from untrusted networks, because this +allows 3rd parties to run arbitrary code on your server! + +<sect3>Using BIOS wakeup to wake your Master backend. +<p>Since I don't use this, I cannot say much about this. If your motherboard +supports any wakeup tool you have to call that tool as "Set wakeuptime +command" with the "Wakeup time format" suitable for that tool. +<sect2>Wakeup the MySQL server using WOL +<p>If your MySQL server and your Master backend are not on the same machine, +you can have the Master backend wake your MySQL server using WOL. You will +find the settings for this in the second page of the mythtv-setup program, +or at the end of <tt>mysql.txt</tt>. The meanings are the same as +discussed in "The WakeOnLan settings" above. + +<sect2>Tips/Tricks: +<p>If, for example, one of the Slave backends is also your desktop computer, +you could simply use a little script as 'server halt command' which first +calls <tt>/sbin/shutdown -t TIMEOUT</tt> where TIMEOUT is a value sufficient +for you to react. You could then popup a window using *dialog, asking for +permission to shutdown. If you cancel the shutdown, simply call +<tt>/sbin/shutdown -c</tt>. + +If you get "nvram-wakeup: /dev/rtc: Device or resource busy" your +set-wakeuptime-script should stop the program that uses <tt>/dev/rtc</tt> before +setting the wakeuptime. +<sect1>Controlling the mythfrontend via telnet +<p>To use this feature you must first enable it in Settings>General>General + +The network control listens on port 6546, as demonstrated below: + +<tscreen><verb> +$ telnet basement 6546 +Connected to basement. +Escape character is '^]'. +MythFrontend Network Control +Type 'help' for usage information +--------------------------------- +# help +Valid Commands: +--------------- +jump - Jump to a specified location in Myth +key - Send a keypress to the program +play - Playback related commands +query - Queries +exit - Exit Network Control + +Type 'help COMMANDNAME' for help on any specific command. + +# help jump +Usage: jump JUMPPOINT + +Where JUMPPOINT is one of the following: +channelpriorities - Channel Recording Priorities +channelrecpriority - Channel Recording Priorities +deletebox - TV Recording Deletion +deleterecordings - TV Recording Deletion +guidegrid - Program Guide +livetv - Live TV +livetvinguide - Live TV In Guide +mainmenu - Main Menu +...snip... +# exit +$ +</verb></tscreen> + +Please note that this feature only allows one connection at a time, so any +new connections will automatically terminate prior ones. + +<sect>Scheduling Recordings. +<p>The MythTV master backend is responsible for managing the schedule for +all TV tuner cards on the master and any slave. Its job is to search the TV +listing for the shows you have requested and assign recordings to the TV +tuner cards. If none of the shows that you've chosen overlap, it simply +records all of them. However, if there are shows where the beginning +and end times overlap, the scheduler follows rules that you've specified or +makes logical decisions about what would be best if you haven't expressed your +preference. Further, the "Upcoming Recordings" page allows you make specific +decisions about what you really do and don't want to record. + +<sect1>Record Types +<p>When you choose a show that you would like to record from the +Options Page, there are eight different types of rules to help the +scheduler find which showings you would like to record. + +<itemize> +<item>Single Record -- record only this title at this specific time and +this station. This is the best way to be sure that a certain showing will +be recorded. However, if the TV listings change and the show is not broadcast +at that time, the show will not be recorded but will be marked as Not Listed +to let you know that you should investigate. + +<item>Find One -- this will record a title once from any of the times +that appear in the TV listings. This is useful for recording a movie +or special that has multiple showings because it allows the scheduler +to choose one that doesn't conflict. It is not a good choice for +recording a single episode of a series because it records the first +available showing of the title without regard to the episode +information. + +<item>Record Weekly -- this records a show whenever the title is listed +on the same channel, weekday and time. Note that if the TV station +changes the schedule for a special episode, it would not be +recorded. However, you can add a Single record for the special +episode. If there are no matching showings in the TV listings, +a Not Listed item will be added to your schedule for the next +time slot to let you know that you should investigate. + +<item>Find Weekly -- this will record a title once per week from any +of the times that appear in the TV listings beginning from the time of +the showing that was selected when the rule was set. This is useful +for news, current events or other programs where the same episode is +shown several times each week but the listings may not include +descriptive information. This may not be a good choice if there are +different episodes shown during the week. + +<item>Record Daily -- this records a show whenever the title is listed +for the time and station on any day of the week. Here again, a show +will not be recorded if the time was altered by the station. If there +are no matching showings in the TV listings, a Not Listed item will be +added to your schedule for the next time slot to let you know that you +should investigate. + +<item>Find Daily -- this will record a title once per day from any +of the times that appear in the TV listings beginning from the time of +the showing that was selected when the rule was set. This is useful +for news, current events or other programs where the same episode is +shown several times each day but the listings may not include +descriptive information. This may not be a good choice if there are +different episodes shown during the day. + +<item>Channel Record -- records one showing of each unique episode from +any of the times the title is listed on this station. This is perhaps +the most common rule to use for most shows. + +<item>Record All -- records one showing of each unique episode from +any of the times this title is listed on any channel. This can be +useful if a station has sister stations where shows are rebroadcast +allowing the scheduler to record rebroadcasts on the other station +when the original airing cannot be recorded. +</itemize> + +<sect1>Scheduling Options +<sect2>Priority +<p>By default, all shows you select have equal value to the +scheduler. There are a set of rules to make good choices when +two or more shows are in conflict. However, priority values let the +scheduler know what you prefer so that it can set the schedule based +on your preferences. + +Initially, recording rule priority values are set to zero. You may choose +to leave everything at "0" and let the scheduler follow rules to guess +what you might prefer when there are conflicts. However, if you have +one or two favorite shows, you may want to increase the priority +value so the scheduler will know that you would prefer recording +these over other shows. You might use certain values to rate shows +so that all favorites are 2. good shows are 1 and extra 'filler' +shows are all -1 for example. You could sort each title on the "Set +Priorities" page to have a unique value so the scheduler can know +which show you'd prefer versus any other show. The choice and style +are entirely up to you. However, the more information you give to +the scheduler, the more likely it will make the choices you would +prefer in the first place. + +The scheduler choices are based on the total priority for a showing by +adding up all priority factors that match the showing. By default, most +of these factors are "0" but you may use any combination to express your +likes and needs. + +<itemize> +<item>Per record rule -- this is the "priority" selection in the "Scheduling +Options" section of the options page and this value is included for any +showings that match the recording rule. You may choose to only use these +values and not use the other factors for the sake of simplicity and clarity. +<item> +Per record type -- Setup->TV Settings->Recording Priorities->General allows +you to add to the priority based on the type. It may make sense to increase +the value for "Single" so that by default they have an extra advantage over +other shows. The default is +1. You may want to decrease the value for Find +rules so that they will be less likely to interfere with regularly scheduled +shows and will be more likely to record in a non-conflicting time instead. +The default is -1. +<item> +Per channel -- Setup->TV Settings->Recording Priorities->Channel Priorities +can be useful if you believe that you prefer any of the shows on certain +channels. This would give all shows on a channel an advantage by default. +<item> +Input priority -- in the "mythtv-setup" program, the "Input Connections" +section allows you to add additional priority in the "Input priority". +This is simply another priority factor but has an interesting effect. If a +card input has a higher value than the other cards, the scheduler will see +that you would rather record showings of episodes on this input rather than a +showing on other inputs. If you have multiple cards of different quality, +you may want to set input priority to encourage the scheduler to record +shows on your best card(s) whenever possible. This can also be useful if you +have multiple video sources which include the same stations. For example, +with digital and analog cable you could increase the digital cable input +preference by 1 to tell the scheduler that you want to record from the +digital channel whenever possible but the channel on the analog input could +still be used when the digital input is busy. +<item> +Custom Priority -- this allows you to add any specialized factors you +would like in order to influence scheduling decisions. See the +<ref id="Custom Priority" name="Custom Priority"> section below. +</itemize> +For any single showing of any show you've chosen to record, these factors +are added together to find the "total priority". This is the priority that +the scheduler uses to decide which showings are given the first choice when +filling in the schedule. + +The scheduling priority of a show may also be used to determine +auto-expiration of recordings when disk space gets full (see <ref +id="Auto-Expire" name="Auto-Expire">, below). + +<sect2>Duplicates +<p>Singles will record without regard to duplicate matching. + +<p>The standard recurring methods of All, Channel, Weekly and Daily use the +descriptive information in the TV listings to try to record only one showing +of each unique episode. However, This goal is sometimes complicated by the +fact that the stations may not include a description for a specific episode +but use a generic description for the series instead. When there is a +generic description, the default behavior is to assume that it may be an +episode that you have not seen and to record it for you. One of the +duplicate matching options is "Record new episodes only". If this is +selected, listing that have an original air date of more than 14 days +earlier are considered repeats and are not eligible to record. Generally, +generic episodes will be marked as repeats also. + +<p>Because of generic episodes and other situations, MythTV offers an +alternative approach where shows may be recorded by choosing from multiple +showings even when the descriptive information is not reliable. All of the +"Find" record types look for matching titles in the listings. If there is a +showing with specific episode information and that episode has recorded +before, that showing is marked as previously or currently recorded. The +scheduler will then choose to record the earliest non-conflicting showing +from any of other remaining showings regardless of the descriptive +information. Generally, Find One is most useful for movies or specials and +the Find Daily and Find Weekly rules are best for news or current events +shows that are repeated. However, these may be useful in other situations +where the standard recording rules may not work correctly. + +<sect2>Conflicts +<p>As you add more shows that you would like to record, the scheduler +will eventually encounter conflicts. If there are two shows at the +same time and you have two or more TV tuner cards, both shows will +record. However, if there are more shows than cards, the scheduler +will have to decide what it thinks it should not record based on the +information you have given. If you see an unexpected situation you +are not "stuck" with the scheduler's choice. You can still tell the +scheduler exactly which shows you do want to record and/or don't +want to record in any situation. + +<sect2>Scheduling decisions +<p>Here are the actual decisions made by the scheduler as it fills in the +schedule. + +<itemize> +<item>Currently recording beats not currently recording -- A recording +in progress can not be moved to another input or time so it "wins" +its current timeslot. + +<item>Single, Daily, or Weekly rules with no match are marked Not Listed -- +If these or Overrides do not match the current listings because the +listings have changed, they are added to the schedule and marked to +indicate that they will not record. + +<item>Rules that could record beat rules that can not record a showing -- +If two rules match the same showing of a program, a rule marked as inactive +or a showing marked as a repeat, for example, yield to the other rule. + +<item>More specific record type is used in place of less specific -- If +two rules match the same showing of a program, preference is given to +Don't Record then Override, Single, Find One, Record Weekly, Find Weekly, +Record Daily, Find Daily, Channel and finally All. + +<item>Higher total priority beats lower total priority -- This is the +core of the scheduling process. Episodes of the highest priority show +are placed on the first available input followed by the next highest +priority show and so on. + +<item>Future start time beats past start time -- If there is an +episode in progress and also a later showing of the same episode, it +is better to record the complete episode. If there isn't another +showing, it will start recording immediately to record the remaining +portion. This should only happen if you add a new rule while the show +is in progress or if the master backend is started after the start time +of a scheduled show. + +<item>More specific record type beats less specific record type -- If +two shows are on at the same time and have the same total priority but +different types they will be sorted by Single then Find One, Record +Weekly, Find Weekly, Record Daily, Find Daily, Channel and finally +All. This only applies if the priorities are the same. + +<item>If both start times have passed, later start time beats earlier start +time -- This attempts to miss the least amount of time. + +<item>If neither start time has passed, earlier start time beats later +start time -- This helps assure that the earliest showing of an episode +has the advantage. + +<item>Lower input id beats higher input id -- The scheduler fills in +open time slots on the first available input for the video source. The +next input is used when there is another show already placed for the +card of the first input. + +<item>Older record rule beats newer record rule -- If two shows are still +equal after all of these other checks, the show whose record rule was added +first is preferred over a more recent addition. + +<item>Postpone showings to resolve conflicts -- If Reschedule Higher +Priorities is set or if a conflict has the same priority as a show +that was scheduled at the same time, the scheduler will check to see +if a scheduled show can be moved to another input or later matching +showing without creating a new conflict so that the conflicting show +can be scheduled to record. + +</itemize> + +<sect2>Reschedule Higher Priorities + +<p>Setup->TV Settings->Recording Priorities->General has a checkbox for +"Reschedule Higher Priorities" which tells the scheduler to try to be a +little smarter in certain situations. If this is checked, the scheduler will +look for situations where a show cannot record because all inputs for the +channel are used for higher priority shows. It will check to see if any of +the other shows could be recorded at another time so that the conflicting +show can be recorded in its place. + +Generally, this is a good strategy but there are tradeoffs. If a higher +priority show is postponed, you will not get to watch it until it is +recorded in the later timeslot. There is also a risk that the TV listings +may change and the later showing may go away. In this rare case the higher +priority show may never record. On the other hand, if you do not use this +option you will miss recording some lower priority shows unnecessarily +unless you manually make similar changes. + +By using Reschedule Higher Priorities, the scheduler will do a better job of +recording as many of your shows as possible when left unattended. It will +also be easy to see that shows have been marked to record at a later time. +You can then decide for yourself when you would prefer to record the first +showing by clicking "Record anyway". + +<sect2>Controlling Your Schedule +<p>The Manage Recordings->Upcoming Recordings page is your control center +for the MythTV scheduler. Unlike other DVR systems, this one page gives you +all of the information and tools you need to see all of your alternatives +and make whatever adjustments you desire. + +The upper half of the screen has a scrollable box listing items that match +your record rules sorted by time. The lower half shows the details for the +highlighted item. There are two 'views' available. Press "1" to include all +of the items that match record rules even if they do not need to be +recorded. Press "2" to focus on just the things that will record and items +that may need your attention. The message in the upper right-hand corner +will remind you when there are conflicts that would prevent one or more +shows from being recorded. + +The items in the list are colored in the record color for things that +will record, white for things that may need attention, gray for those +that do not need to record and yellow when there is a time conflict. +Items at the top of the list may also be highlighted indicating that the +recording is in progress. + +Along with the channels, start times and titles, the right-hand column has +a status code. Numbers indicate which card number has been assigned to +record the show. Letters are used to indicate the reason that something +will not be recorded. Just below the box is a short status message for the +highlighted item that indicates the type of record rule that was matched, +the "total priority" for this showing and a one or two word explanation of +the status code. If you press SELECT, you will see more information about +the status. + +There are a few status codes that may require your attention. "C" indicates +that there are more overlapping shows to record than there are TV tuners to +record them. "L" indicates that the scheduler found that it may be better to +record a later showing of this episode. These states happen as a result of +your choices and should normally reflect your preferences. However, you may +notice situations where you would like to modify the scheduler's initial +choices. + +The first thing you can do is to highlight an item and press INFO to +see the recording options page. From this page you can change the +record rule type, the duplicate matching rules, or raise or lower the +priority to resolve whatever problem you noticed. + +Additionally, you can treat any individual showing as an exception that you +do want to record or don't want to record. To use these "override" features, +highlight the item and press SELECT. You will see a message explaining the +current status and at least an "OK" button to exit without making changes. + +For items scheduled to record, there will be a button for "Don't record" +which will prevent recording this showing but will still allow the same +episode to record in the future. If there is episode description +information, you may also see a button for "Never record". This prevents +recording this showing and tells MythTV to remember that this is an episode +that you've seen or don't need to see if it is ever in the TV listings +again. + +For items that are not scheduled to record, the message will describe the +reason and in the case of "C" or "L" it will include a list of the shows +that are scheduled to record instead. For any item that could potentially be +recorded there will be buttons for "Edit Options" and "Add Override". "Edit +Options" will allow you to change the options for the existing record rule +such as raising the priority so that the show will record. These changes +would apply to this and all future showings that match this record rule. +"Add Override" will allow you to set options that apply to the specific +showing without affecting the recurring record rule. + +If you return to an override page after an override has already been set, +you will also see a "Clear Override" to undo your changes. This option makes +it very easy to try out some "what if" attempts when deciding on your best +strategy in a difficult situation. + +For a recording in progress, there will be a "Change Ending Time" button. +This will take you to the options page for a Single or Override or create +an Override if it is a recurring rule. Here you can go to the Recording +Options section to change the program end time offset. If you extend the +end time so that it overlaps upcoming recordings, the schedule will change +to accommodate the new end time. This may cause a conflict or later showing +even for a show with higher priority. Therefore, it is a good idea to +check your schedule after changing the end time of a recording in +progress. + +<sect1>Storage Options +<sect2>Recording Profile +<p>Each recording rule can be configured with a different recording +profile. For example, colorful cinematography can be configured with a +"High Quality" profile, while 'talking heads' interviews shows can be +configured with a "Low Quality" profile. These recording profiles need to +be configured before using them (see <ref id="Recording" name="Recording">, +above). + +<sect2>Recording Group <label id="Recording Group"> +<p>For organization of the "Watch Recordings" screen and the MythWeb +interface, recordings can be assigned into "recording groups". + +<sect2><ref id="storagegroups" name="Storage Groups"> +<p>This allows you to select any special "Storage Groups" you may have +created to determine where recordings from this rule should be stored +on your disks. The "Default" storage group is always available. + +<sect2>Playback Group <label id="Playback Group"> +<p>This selects a set of pre-configured playback parameters which can be +created and edited in Setup->TV Settings->Playback Groups. When the +recording is played, the values from this playback group will be +used. This allows you to choose a default time stretch value, skip and +jump amounts appropriate for this type of television program. + +<sect2>Auto-Expire <label id="Auto-Expire"> +<p>MythTV will "autoexpire" old recordings to make room for new recordings +when disk space gets filled up. This option can be set to "Don't allow +auto expire" to prevent these recordings from being automatically deleted +when disk space fills up. + +<p>The default setting is for all scheduled recordings to be eligible +for auto-expiration; this can be changed in the Settings->TV +Settings->General page by manipulating the "Auto Expire Default" +checkbox. + +<p>The default auto-expire policy is "Oldest Show First"; the oldest +recordings are deleted first. The "Lowest Priority First" method +chooses to expire the lowest-priority recordings first. + +<sect2>Episode Limit +<p>An episode limit can also be configured to limit the maximum number +of episodes recorded of a single series, to restrict that series' disk +usage. If this is set, you can further decide what to do when this +limit is reached; either stop recording that series, or to delete the +oldest episodes in favor of the new ones. + +<sect1>Post Recording Processing +<sect2>Commercial Flagging +<p>Select whether or not to automatically flag commercials for these +recordings. Commercial Flagging parameters can be set in +Setup->TV Settings->General. + +<sect2>Transcoding +<p>Select whether or not to automatically transcode recordings to save +disk space. Before using this, you must first enable auto-transcode in +the recording profile and configure the transcoding parameters; see +<ref id="Recording" name="Recording">, above. + +<sect2>User Jobs +<p>User Jobs allow you to configure up to 4 custom commands to run on +recordings. They can be configured in mythtv-setup. The following +tokens have special meaning when used in the User Job commands: + +<itemize> +<item>%DIR% - the directory component of the recording's filename +<item>%FILE% - the filename component of the recording's filename +<item>%TITLE% - the title of the recording (e.g., name of the series) +<item>%SUBTITLE% - the subtitle of the recording (e.g., name of the +episode) +<item>%DESCRIPTION% - description text for the recording (from guide +data) +<item>%HOSTNAME% - the backend making the recording +<item>%CATEGORY% - the category of the recording (from guide data) +<item>%RECGROUP% - the <ref id="Recording Group" name="recording +group"> +<item>%CHANID% - the MythTV channel ID making the recording +<item>%STARTTIME% - the recording start time (YYYYMMDDhhmmss) +<item>%ENDTIME% - the recording end time (YYYYMMDDhhmmss) +<item>%STARTTIMEISO% - the recording start time in ISO 8601 format +(YYYY-MM-DDTHH:MM:SS) +<item>%ENDTIMEISO% - the recording end time in ISO 8601 format +<item>%PROGSTART% - the recording's start time (from guide data; +YYYYMMDDhhmmss) +<item>%PROGEND% - the recording's end time (from guide data) +<item>%PROGSTARTISO%, %PROGENDISO% - the recording's start and end +time in ISO 8601 format. +</itemize> + +<sect1>Advanced Recording Options +<sect2>Creating Power Search rules with Custom Record +<p> +MythTV's "Custom Record" feature gives you unlimited control for creating +specialized search recording rules to meet your needs. It allows you to +choose your criteria to search for matching shows based on any of the +information in the program listings, channel information, time functions and +more. This goes beyond the capabilities of any other DVR system and it is +unlikely that this level of scheduling customization will ever be available +in any commercial DVR system. + +<sect2>Getting Started +<p> +Go to Schedule Recordings->Custom Record. This page, helps you build a +database search one clause at a time. Each added clause further limits +which showings will be matched in the TV listings. You can test the +search at any time and when you are done, you can save your search as a +recording rule. + +To familiarize yourself with how you can create custom rules, create a +simple rule to record "Nova" only in primetime. + +The first item at the top of the page allows you to edit an existing rule +or create a new rule. Leave it on "<New rule>". Arrow down to the +third item which says "Match an exact title". Right and left arrows would +allow you to select any of several prefabricated pieces or full examples +but leave it on the default for now. Arrow down to "Add this example +clause" and press SELECT (Enter or Space on a keyboard). The large text +box should now show: +<tscreen><verb> + program.title = 'Nova' +</verb></tscreen> +As you have probably guessed, this says that we want to search for all +programs with the title "Nova" regardless of the time, day, channel, etc. + +If you do not receive a PBS station that carries "Nova" or would like to use +another title, edit the title by pressing the down arrow to highlight the +text box and right arrow over the the word "Nova". If you are using a +keyboard you can simply delete the four letters and type a different title +between the quotes. With a remote control, you can do 'cell phone' style +text entry with the number pad. The delete key is the "X" in the grouping +for "1", zero is grouped with "9" and "0" acts as the "Caps Lock" key. You +can press ENTER in the text box to popup a virtual keyboard. + +Note: the text box honors many familiar Emacs control keys. It is also +possible to cut and paste text into the text box so you can edit with a +favorite editor or insert a rule sent in email or from other sources. + +In any case, choose a title that is shown both in primetime and late night +or daytime. Next, click the "Test" button. You should see a list of the +upcoming episodes for "Nova" just as if you had clicked the Upcoming +button for "Nova" elsewhere in MythTV. + +Press ESC to go back to the Custom Record page. Move to the example +selector then press the right or left arrows until you find "Only in +primetime". Click "Add this example clause". You should now see: +<tscreen><verb> + program.title = 'Nova' + AND HOUR(program.starttime) >= 19 + AND HOUR(program.starttime) < 23 +</verb></tscreen> +Click "Test". You should now see a shorter list with only the showings that +begin between 7PM and 11PM. To create a rule for this, press ESC to go back +to the custom page and move to "Rule Name:" then type "Nova" or anything +else you would like. This is only a label and will not affect the search +results. Once a name has been entered, the "Record" button will light up. +Click this to enter the recording options page. If you named it "Nova" the +title will say "Nova (Power Search)". Set whatever options you would like +then click "Save these settings". You now have a special rule to record +"Nova" but only when it is shown in primetime. + +You can make further modifications to this rule by returning to the Custom +Record page then press the right or left arrow keys on "Edit Rule:" until +you find "Nova". You can experiment and test but the saved rule will not +be updated until you click "Record" then "Save these settings". + +To remove this, or any other rule, you can go to the "Recording Priorities" +page, arrow down to the title, press Enter and change the the recording type +to "Do not record this program" then "Save these settings". + +<sect2>How it Works +<p> +MythTV stores TV program information in a database and uses the Structured +Query Language (SQL) to access the data. Information about each TV program +is stored in the 'program' table and information about each TV station you +receive is stored in 'channel'. These two tables are used in the scheduler +queries and their columns are available to be used in your rules. The rules +you create are stored in 'record'. + +Normal rules in MythTV simply match the title in the rule with the titles +in the 'program' table. MythTV also has search rules for "Titles", +"Keywords" and "People". These store the key phrase in the description +column of the rule and includes them in specialized SQL replacements for +the normal title check. There is also a type called "Power Search" which +takes the raw SQL in the description as the replacement for title +matching. + +Custom Record is a tool to help you build valid SQL for Power Search rules. +You do not need to be a SQL expert to use Custom Record because the +examples are known to work correctly and are usually self-explanatory so you +can choose the pieces you need then modify them. Many powerful solutions to +unique problems are possible by combining the examples. With some creativity +and some knowledge of SQL, the possibilities are limitless. + +<sect2>Common Tricks and Tips +<p> +The example clauses marked "complete example" are actual rules that have +been used to address specific problems. You may find that some of these +are useful for you as-is or with slight modifications. These show off how +powerful custom rules can be but there are also several simple idioms that +you may find useful for many of the shows you would like to record. + +Wait for a known title -- If there is a movie that you anticipate will be +televised in the coming months but is not yet in the listings, you can +select "Match an exact title", edit the movie title, click "Record" then +choose "Record one showing of this title". The rule will wait weeks, months +or years until this title shows up in your listings then it will record one +showing. These rules have no impact on the scheduler throughout the day and +only take a tiny fraction of a second when the master backend starts or when +the listings are updated. + +Silence series out of season -- "Celebrity Poker Showdown", for example, +will have new episodes for a while then long periods where reruns are shown +dozens of times per week. By checking the previously shown flag you can +create a rule that will only match new episodes. Therefore, your schedule +won't be polluted with dozens of entries marked as "Repeat" or "Previously +Recorded". +<tscreen><verb> + program.title = "Celebrity Poker Showdown" + AND program.previouslyshown = 0 +</verb></tscreen> +This allows you to keep rules for your favorite shows that are dormant while +out of season but will spring back to life when new episodes appear. + +Choose showings on certain days -- Several cable stations will show their +highest rated shows a dozen on more times per week. However, the scheduler +only needs two or three choices to do a good job of making a flexible +choice. +<tscreen><verb> + program.title LIKE "Celebrity Fit Club%" + AND DAYNAME(program.starttime) = "Sunday" +</verb></tscreen> +This says to choose any showing of an episode that hasn't been recorded +when it appears on Sunday. This prevents all the other showings during the +week from being listed in the schedule. + +Notice the word "LIKE" and the "%" at the end. This does wildcard matching +so that this would match even if the title ended with "2". "III" or +":Revenge of the Snapple Lady". This can be useful where the title may +change from one season to the next like "Survivor: %", "Big Brother%" or +"The Amazing Race%". + +<sect2>Working with SQL +<p> +As you experiment, it is possible that you may misplace a quote or mistype a +word. If there is a mistake when you press "Test" or "Record" you will see +an error message returned from the database. This will usually give you a +good idea about what needs to be fixed. However, for more subtle MySQL +syntax errors, you can find more information in the documentation at <url +url="http://dev.mysql.com/doc/mysql/en/" +name="http://dev.mysql.com/doc/mysql/en/">. This contains a lot of +information that can be useful for Power Search rules such as the "Date and +Time Functions". There are many other good resources for SQL on the Web. + +While the example clauses demonstrate how to use many of the data columns, +you can get a more complete list of all the columns that are available by +using a MySQL client program: +<tscreen><verb> +$ mysql -u mythtv -pmythtv mythconverg +mysql> describe program; +mysql> describe channel; +</verb></tscreen> +This will show the names of all of the columns along with their type and +default value. Most are easy to understand but a few need some explanation +in order to use them effectively with Power Search. +<itemize> +<item>"program.category_type" holds one of these exact four strings: "movie", +"series", "sports" or "tvshow". + +<item>"program.airdate" is a string representing the year of release for +movies and may have no meaning for other types of shows. + +<item>"program.stars" is a floating point number from 0.0 to 1.0. On a +four star scale, 1.0 would be four stars, 0.75 would be three stars and so +on. + +<item>"program.originalairdate" if provided is the date when a show +was, or will be, first televised. This may be useful for finding +episodes before or after a certain date such as finding just the +original series of "Battlestar Galactica". + +<item>"program.previouslyshown" is a column created by MythTV to try to +determine if a showing is more than 14 days after its original air date or +if the show was marked as a repeat and did not have a date for the first +airing. If this is "0" it usually means that this is a brand new show or a +rebroadcast within the first two weeks. + +<item>"program.generic" is a column created by MythTV to try mark +showings for a series where the specific episode information is not +included. When these generic showings appear, it is impossible for the +system to determine if they are repeats of the same episode(s) or if +they are all different episodes. + +<item>"program.first" is a column created by MythTV to mark the first +showing in the current listings for each episode, movie or special. +Choosing to match only the "first" showing can be useful for sports +that are brodcast live then repeated. + +<item>"program.last" is a column created by MythTV to mark the last +showing in the current listings for each episode, movie or special. +If a showing is marked both "first" and "last" then it is the only +showing of that program in the current TV listings. + +<item>"program.programid" is the Tribune Media Service database record +identifier for each program description. In general, these start with a two +letter prefix, MV, EP, SP or SH that correspond to the +"program.category_type". For most, the last four digits are "0000" except +EP where the last four digits are the episode number in the series. Note +that these are generated by TMS and not the show's producers but they are +usually in the same order as the original air dates for the episodes. + +<item>"program.videoprop" also "audioprop" and "subtitletypes". +These columns contain bit flags for a variety of attributes that +may be associated with a program. These are filled with information +offered by the TV listings provider. However, your listings source +will not have information for all of the available flags. Therefore, +some of these may not be useful for your search rules. This information +is organized in "sets" and the MySQL function FIND_IN_SET() can be used +to test for any of these flags. For example: +<tscreen><verb> +FIND_IN_SET('SURROUND', program.audioprop) > 0 +</verb></tscreen> +would be true for the programs where the surround sound bit is present. +To see all of the available attribute names: +<tscreen><verb> +$ mysql -u mythtv -pmythtv mythconverg +mysql> SHOW COLUMNS FROM program LIKE '%prop'\G +mysql> SHOW COLUMNS FROM program LIKE 'subtitletypes'\G +</verb></tscreen> +</itemize> +Finally, if you are doing something very experimental and a column is not +giving you the results you had anticipated, you can always check the MythTV +source code to see exactly how a column is used. The open source for MythTV +is available from <url url="http://www.mythtv.org/" +name="http://www.mythtv.org/"> . + +<sect1>Scheduling with more than one Input +<p> + +MythTV is designed to allow recording television programs from one or more +service providers, or video source, on one or more video input from each +provider. Some inputs may not be allowed to record at the same time as +each other while others may record simultaneously. + +A television station may be broadcast on more than one channel from one +provider or may be available on channels from two or more providers. If a TV +station is available from more than one source, the video quality or type of +broadcast may differ. Therefore, MythTV allows you to control how you would +like the scheduler to select the best channel and input for a show which is +available on more than one input or more than one channel. + +<sect2>Mutually Exclusive Inputs +<p> +A single TV capture card may have video connections to more than +one of its inputs and each input may be from a different service. The card +may only be allowed to record from one of these inputs at one time because +there is only one encoder on the card that actually captures the content. + +<figure loc="here"> +<eps file="BlockDiagramofavideocapturedevice.eps" height="1cm"> +<img src="BlockDiagramofavideocapturedevice.png"> +<caption> +</caption> +</figure> + +These are mutually exclusive meaning that only one input or the other +may record at a given time but not both. + +Usually, inputs on different cards can record at the same time +but two or more inputs on the same card cannot. However, there are cases +where inputs on different cards should not be allowed to record at the +same time, for example, a firewire card and s-video analog card connected +to the same set top cable box. + +<tscreen><verb> +| +| coax +--------------+ firewire ------------------+ +| .-=|Cable Provider|=------------=| Card 1 input 1 | HDTV +| | |HD/Cable STB |=--. +-----|||||||||||| +| | +--------------+ | s-video ------------------+ +| | `---------=| input 2 | Digital +|wall | coax | Card 2 | +|=---=^=------------------------------=| input 3 | Cable +| +-----|||||||||||| +</verb></tscreen> + +Input 1 and input 2 receive content from the same set top box and the +channels can not be tuned independently. Therefore only one of these two +inputs should be used at any given time. The solution is to create an "Input +Group" with <bf>mythtv-setup</bf> in "Input connections". Including these +two inputs in the same Input Group will tell the scheduler that these are +mutually exclusive and may not record at the same time. Inputs 2 and 3 are +automatically mutually exclusive because they are on the same card so there +is no need to create an Input Group for these inputs. + +Cards such as the Hauppauge PVR-500 are able to record as two cards +simultaneously because it has two MPEG-2 encoders and each encoder appears +as a separate device. DVB cards may be allowed to capture content from more +than one channel at a time if the channels are in the same MUX. + +<sect2>Stations, Channels and Video Sources +<p> +Although we may be accustomed to thinking of a broadcast station and its +channel number as being synonymous, stations and channels are very different +things. A "station" is in a building with wires and employees. A "channel" +is a carrier frequency or digital ID that carries a broadcast stream. The +same TV station may be broadcast over different frequencies in different +cities or by different providers in the same city. The same frequency will +carry different stations in different cities. In the digital realm of DVB +and ATSC (HDTV), it is even possible for a single frequency to carry +multiple program streams but each of these streams of content are actually +different channels that the receiving devices can 'tune' to independently. + +<itemize> +<item>Station: building +<item>Channel: frequency +</itemize> + +In MythTV, a "video source" is a set of channels from a provider, or over +the air, that can be received by an input. The set defines the channels and +the broadcasters primarily associated with each of those channels. If you +have more than one device or cable from the same provider connected to more +than one card and input, you only need to create one video source in +mythtv-setup then associate that one source with each of these connected +inputs. This will let your MythTV system know that the same channels and +their TV listings are available to be recorded from any of these inputs. + +For example. A MythTV system may have two capture cards. Both have a cable +connected to the coaxial connectors. These cables carry the local cable TV +service. In mythtv-setup, the user should create one "Video source" called +"Cable", for example. Under "Input connections", "Cable" should be +associated with each of the two tuner inputs. The scheduler will then know +that any program on one of the channels from the "Cable" source could be +recorded by either card from the card's tuner input. + +You need to create a different video source for each provider or service +that has a different set of channels. Each input with a connection to that +service should be associated with the video source for that service so the +system will know which set of channels are available for each of your active +inputs. + +Let's say that this user also has one digital cable set top box. The digital +cable service carries channels that are not available over basic cable. The +user would create another source called "Digital". This set top box is +connected to the second card by S-Video so under "Input connections", +"Digital" is associated with the S-Video input of card 2. The system would +then know that programs on channels from the Digital source can only be +recorded from this input. Further, the scheduler understands that it can +only record one show at a time from card 2 so it can assign Cable or Digital +shows to the card but not both at the same time. + +Some TV stations may be broadcast over a channel from the Cable source and +also broadcast over a channel from the Digital source. Note that two +channels carrying the same primary station may not have the same TV listings +due to carrying the primary station part time, including local programming +exclusive to one of the channels, the channels may be in different +timezones, etc. Listings information must be associated with each channel +even if two or more channels report that they carry the same station. + +<sect2>Order of Inputs +<p> +By default the scheduler chooses the first (lowest numbered) input which has +a showing of the scheduled program as it fills the schedule. If a lower +priority show is on at the same time as a higher priority show that has been +assigned to input 1, then input 2 will be used next and so on. Therefore, +configure your best card and input first and next best card and input +second. There may be differences in the type or brand of capture card, +signal quality from the cable, system resources such as disk space, CPU, +etc. By configuring your best input first, more recordings, and your highest +priority recordings, will use that input. + +A common situation is that a newer and better card is added last. For +example, you may initially setup your system with two analog cable cards and +then add a HDTV card. If NBC is on a cable channel and "The Apprentice" is +shown in HDTV on an NBC HD channel, the scheduler would still prefer analog +inputs 1 and 2 over the new HD input 3. + +So, if you'd like the scheduler to prefer a new source, the simplest thing +is to run <bf>mythtv-setup</bf> and "Delete all capture cards" then enter +your cards and inputs in your preferred order. This will not remove your +sources and channels - you want to keep those and only renumber your cards +and inputs. In this example, once the changes have been made and the Master +Backend is restarted, the scheduler would then choose "The Apprentice" in HD +on the new input 1 and only use the analog inputs (now numbered 2 and 3) +when the HDTV input was occupied with another show. + +<sect2>Matching Callsigns +<p> +If a recording rule is a type that can record from any channel, "The +Apprentice" would match for any channel that shows episodes which may +include CNBC or BRAVO. However, for Single, Timeslot, Weekslot or Channel +rules, "The Apprentice" would only match showings on the selected station as +identified by the "callsign". For example, KVBC is an NBC affiliate on +channel 3. Channel 733 is KVBCDT which is HDTV over cable from the same +station. If a Single record rule was set for "The Apprentice" on KVBC +channel 3, it could not record this showing from KVBCDT on 733. If 733 was +chosen when the rule was saved, channel 3 could not be used to record. + +However, the "Channel Editor" in mythtv-setup can be used to change the +Callsign for channel 733 to "KVBC". MythTV would then understand that both +of these channels are from the same broadcast station. Assuming the HDTV +input was input number "1", "The Apprentice" would record on 733. If, +however, this HDTV input already had a higher priority show assigned to it +in that time slot, "The Apprentice" would be assigned to KVBC channel 3 on +input 2. + +Having two channels with the same callsign may affect how program +information is shown in mythfrontend. If two sources have the same callsign +and channel number, the program guide and program lists will only show one +instance of the channel number and callsign. If the same callsign is on two +different channel numbers, both will be shown and if two sources have +different callsigns with the same channel number, both of those will be +shown. + +Continuing with the example above, the Electronic Program Guide would +include rows for both "3 KVBC" and "733 KVBC". If channel 3 KVBC was also +included in the Digital cable source, the EPG would still include just one +line for "3 KVBC" even though there are two different channels, Cable and +Digital, with this identification. Regardless of how these are displayed and +which "KVBC" channel you select to add a rule to record "The Apprentice", +the scheduler will pick the best channel, source and input to record "The +Apprentice" on "KVBC". + +<sect2>Using Priorities to Prefer an Input +<p> +The fundamental concept to keep in mind is that the MythTV scheduler will +choose the lowest numbered input available when showings have the same +priority. If there are factors that cause two showings of the same show to +have different priorities then the higher priority showing will be +considered before the showings with lower priority. + +<sect2>Input Priority +<p> +"Input Connections" in mythtv-setup includes a box to set "Input priority" +which defaults to "0". If a value is set, that amount will be added to the +"total priority" for showings on that input. This can be used to influence +using favored cards or not using less favored cards unless necessary. + +Let's say the "The Apprentice" is on at 8:00pm with a priority of 3. "Who +Cares" is -2 and an episode is shown at 8:00pm then repeated at 11:00pm. The +scheduler would assign "The Apprentice" to card 1 and "Who Cares" to card 2 +at 8:00pm. If the input priority for the input on card 2 was changed to -1, +"Who Cares" would have a total priority of -2 for showings on card 1 and -3 +for showings on card 2. The scheduler would assign "The Apprentice" to card +1 at 8:00pm and "Who Cares" to card 1 at 11:00pm when the better card is +available. If there was another higher priority show at 11pm, the next best +choice for "Who Cares" would be card 2 at 8pm with the priority -3. + +Card 1 and 2 have input priority "0": + +<figure loc="here"> +<eps file="Card1 Pri 0 Card2 Pri 0.eps" height="1cm"> +<img src="Card1 Pri 0 Card2 Pri 0.png"> +<caption> +</caption> +</figure> + +<tscreen><verb> + Time Title Priority Card Status + 8:00 The Apprentice +3 1 Will Record + 8:00 Who Cares -2 2 Will Record +11:00 Who Cares -2 1 Earlier Showing +</verb></tscreen> + +Card 2 with input priority "-1": + +<figure loc="here"> +<eps file="Card1 Pri 0 Card2 Pri -1.eps" height="1cm"> +<img src="Card1 Pri 0 Card2 Pri -1.png"> +<caption> +</caption> +</figure> + +<tscreen><verb> + Time Title Priority Card Status + 8:00 The Apprentice +3 1 Will Record + 8:00 Who Cares -3 2 Later Showing +11:00 Who Cares -2 1 Will Record +</verb></tscreen> + +Card 2 at "-1" but higher priority shows at both 8 P.M. and 11 P.M.: + +<figure loc="here"> +<eps file="Card1 Pri 0 Card2 Pri -1-TDS.eps" height="1cm"> +<img src="Card1 Pri 0 Card2 Pri -1-TDS.png"> +<caption> +</caption> +</figure> + +<tscreen><verb> + Time Title Priority Card Status + 8:00 The Apprentice +3 1 Will Record + 8:00 Who Cares -3 2 Will Record +11:00 The Daily Show +1 1 Will Record +11:00 Who Cares -3 2 Earlier Showing +</verb></tscreen> + +Note the two different effects, each of which may be what you desire +depending on circumstance. If input priorities are equal, shows will record +at the earliest time if any input is available. If input priorities differ, +shows may be postponed to a later time in order to record on the best input. + +<sect2>Channel Priority +<p> +Priority can be added for individual channels (remember, frequencies from a +video source, not stations). This can be used to tell the system that you +generally prefer the content of the station on a channel over the formats of +other stations. You may want to raise the priority for ESPN, SciFi, Comedy +Central or lower the priority for CSPAN, CourtTV, etc. If the same station +is on two different channels, you can use channel priority to have the same +effect for these channels as input priority would have for whole inputs. + +For example, say CNN is on analog channel 20 and there is an HD CNN on 750. +You may not want to tie up the HD input for news originating in standard +definition. Under TV Settings->Recording Priorities->Channel Priorities you +could set channel 750 to -1. The scheduler would then prefer to record CNN +shows on any analog channel 20 before considering using 750 only when there +are no analog inputs available. + +<sect2>Preferred Input +<p> +For an even finer grain of control, there is a per rule option to specify +which input should be preferred for showings that match the rule. By +default, this adds +2 to the priority for showings on the specified input. + +For illustration, let's say there will be a Space Shuttle launch on CNN that +will be broadcast in high definition. Adding a rule to record the launch +with priority "0" should default to channel 20 on input 2. Channel 750 would +have this at -1 due to the channel priority set in the previous example. If +on the recording options page for this rule, the "Scheduling Options" had +the input set to prefer the HD input on card 1, then the showing on channel +750 for this input would be increased in value by +2 for a total of +1 and +would be the best choice for this launch coverage. While this one rule +would prefer the HD input with channel 750, all other rules that match shows +on CNN would still prefer channel 20. + +Note that this will not work properly if the preferred input priority does +not out weigh differences in input and channel priorities. The value of the +priority boost when this option is chosen defaults to +2 but can be modified +in TV Settings->Recording Priorities->Set Recording Priorities. + +<sect2>HDTV Priority +<p> +In the preceeding fictious example, the Space Shuttle launch is broadcast in +high definition and a preferred input is selected to give preference to the +HD input. However, TV listings from zap2it.com through the DataDirect +service may allow this to work without having to use this per rule option. + +In Settings->Recording Priorities->Set Recording Priorities there is an +option for "HDTV Recording Priority". This value will be added automatically +if the listings for the show have the "hdtv" flag set. DataDirect will set +this flag for shows known to be broadcast in HDTV on HD channels. However, +the flag is not set for standard definition channels. This is another +example of the listings being different for the same station on a different +channel. If the HDTV priority is set to "+2", the shuttle launch would +automatically have a total priority of +1 so that channel 750 would be +preferred over channel 20 for this HDTV broadcast. + +Channel "750 CNN" at priority "-1" and HDTV broadcast priority at "+2": + +<figure loc="here"> +<eps file="Card1 HDTV Card2 Cable.eps" height="1cm"> +<img src="Card1 HDTV Card2 Cable.png"> +<caption> +</caption> +</figure> + +<sect2>Custom Priority <label id="Custom Priority"> +<p> +<figure loc="here"> +<eps file="add.eps" height="1cm"> +<img src="add.png"> +<caption> +New for MythTV 0.21</caption> +</figure> + +While Input, Channel, and HDTV Priority can be used for indicating a +preference for certain programs and inputs, there may be circumstances that +cannot be resolved easily with these standard features. MythTV version 0.21 +includes a feature for "power priority". The Custom Priority editor in +mythfrontend's "TV Settings" screen is similar to Custom Record, however, +Custom Priority allows you to create specialized power priority factors to +influence scheduling decisions. + +For example, the 'program.closecaptioned' flag can be used in a +similar way as the 'program.hdtv' flag. + +<tscreen><verb> +Priority Rule Name: Closed Captioned priority +Priority Value: 2 +program.closecaptioned > 0 +</verb></tscreen> + +This will raise the priority of shows marked with "CC" over those that are +not by applying the "Priority Value" whenever the SQL fragment evaluates to +true. If the expression evaluates to false for a showing, the "Priority +Value" is not applied. + +<tscreen><verb> +Priority Rule Name: Priority when shown once +Priority Value: 1 +program.first > 0 AND program.last > 0 +</verb></tscreen> + +The "first" and "last" flags for an episode will only be set for the +same showing when there is only one showing of that episode in the +current TV listings. This rule would raise the priority in these cases +so that these shows would have an advantage to record in their only +available time slot. + +<tscreen><verb> +Priority Rule Name: Input 1 signal quality +Priority Value: -1 +cardinput.cardinputid = 1 AND +channel.channum IN (3, 5, 39, 66) +</verb></tscreen> + +A common issue with two or more analog capture cards is that one of +the cards may have more interference on some channels than the same +channels on other cards. This example gives a disadvantage to the +channels in this list but only for the first input. Therefore, a show +on channel 39 would choose input 2 or 3 if possible but for channels +not in this list, input 1 is still the first choice. + +The Custom Priority editor includes many example fragments and complete +examples that can be used or you can create your own to suit your needs. + +<sect>MythPlugins. <label id="mythplugins_"> +<p>MythTV has a rich set of plugins available. Once you have downloaded +the tarball, untar it and run the <bf>configure</bf> script: + +<tscreen><verb> +$ tar -xjf mythplugins-0.21.tar.bz2 +$ cd mythplugins-0.21 +$ ./configure --help + +Usage: configure [options] +Options: [defaults in brackets after descriptions] +NB: all --enable-* options can be reversed with --disable-* + +Generic options: + --help print this message + --enable-all Enable all options + --enable-opengl enable OpenGL (Music and Gallery) [default=no] + +MythBrowser related options: + --enable-mythbrowser build the mythbrowser plugin [default=yes] + +MythDVD related options: + --enable-mythdvd build the mythdvd plugin [default=yes] + --enable-transcode enable DVD ripping and transcoding [default=no] + --enable-vcd enable VCD playing [default=no] + +MythGallery related options: + --enable-mythgallery build the mythgallery plugin [default=yes] + --enable-exif enable reading of EXIF headers [default=no] + +MythGame related options: + --enable-mythgame build the mythgame plugin [default=yes] + +MythMusic related options: + --enable-mythmusic build the mythmusic plugin [default=yes] + --enable-fftw enable fftw visualizers [default=no] + --enable-sdl use SDL for the synaesthesia output [default=no] + --enable-aac enable AAC/MP4 audio file decompression [default=no] + +MythNews related options: + --enable-mythnews build the mythnews plugin [default=yes] + +MythPhone related options: + --enable-mythphone build the mythphone plugin [default=yes] + --enable-festival enable festival TTS Engine [default=no] + +MythVideo related options: + --enable-mythvideo build the mythvideo plugin [default=yes] + +MythWeather related options: + --enable-mythweather build the mythweather plugin [default=yes] +</verb></tscreen> + +The sections detailing configuration of the plugins assume that you are +already in the <tt>~/mythplugins-0.21/</tt> directory. + +Note that a single <bf>configure</bf> script now does configuration for all +modules. By default, it will compile all modules. If you do not wish to +compile a module, either because it is of no use to you, or you do not have +the prerequisites, the simplest course of action is to go through the +various sections below, satisfying the prerequisites, and then compile all +modules at once. + +For example, you would only like to compile and install MythGallery and +MythMusic. For MythGallery, you would like to use the EXIF data in the .JPG +file to present additional information onscreen. For MythMusic, you would +like to enable support for the opengl and FFT visualizations. The command +line would look like: + +<tscreen><verb> +$ cd ~/mythplugins-0.21 +$ ./configure --disable-all --enable-opengl --enable-mythgallery --enable-exif --enable-mythmusic --enable-fft +$ qmake mythplugins.pro +$ make +$ su - +# make install +# exit +$ +</verb></tscreen> + +For simplicity, the examples below will disable compilation of all other +modules other than the one being discussed. + +<sect>MythWeb. +<p>MythWeb allows you to use a web page to control various aspects of your +MythTV system. MythWeb is a separate application, but it's dependent on +MythTV being installed and operational. + +<sect1>Installation and prerequisites + +<p>Mythweb is a part of the <bf>mythplugins</bf> package. See <ref +id="mythplugins_" name="MythPlugins"> for instructions on downloading the +tarball. The next step depends on whether your distribution has a web server +and if you have PHP support. + +<sect2>Mandriva +<p>Mandriva has <bf>apache</bf> and <bf>PHP</bf> pre-packaged, so +installation is quite simple. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Mandriva 9.1 users, perform the following: +</caption> +</figure> +<tscreen><verb> +# urpmi apache2 apache2-mod_php php-mysql +# chkconfig --level 345 httpd on +# /etc/rc.d/init.d/httpd restart +</verb></tscreen> + +<sect1>Completing the installation +<p> +<tscreen><verb> +$ cd ~/mythplugins-0.21/mythweb +$ su +# mkdir /var/www/html/mythweb +# cp -r . /var/www/html/mythweb +# exit +$ +</verb></tscreen> + +By default, MythWeb uses an Apache <tt>.htaccess</tt> file to restrict +access to the website and to configure some variables. + +To create the password file for Apache (if your system doesn't already have +one), you could do something like this: +<tscreen><verb> +# cd /var/www +# htpasswd -c htpasswd mythtv +New password: +Re-type new password: +Adding password for user mythtv +</verb></tscreen> + +See the man page for <bf>htpasswd</bf> for more examples. + +To access the web page, open a web browser and use <bf>http://[name or ip +address]/mythweb/</bf> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Make sure that you have a trailing slash on the URL, +otherwise you will get a <tt>404 Page not Found</tt> error. +</caption> +</figure> +<sect1>Resetting the key binding table +<p>MythWeb allows you to configure which keys are bound to which actions +within MythTV. If you'd like to reset this back to the default, execute the +following command: +<tscreen><verb> +$ echo "delete from keybindings ;" | mysql -u mythtv -pmythtv mythconverg +</verb></tscreen> +<sect1>Resetting the theme. +<p>If you find yourself wedged into a theme that isn't working, open your +web browser and go to site: +<tt>http://mythweb_name_or_ip_address/mythweb/settings.php?RESET_THEME=yes</tt> +<sect>MythGallery. +<p>MythGallery is a photo and slideshow application. MythGallery is a +separate application, but it's dependent on MythTV being installed and +operational. +<sect1>Installation and prerequisites + +<p>MythGallery is a part of the <bf>mythplugins</bf> package. See <ref +id="mythplugins_" name="MythPlugins"> for instructions on downloading the +tarball. + +There are a number of transitions available, some requiring OpenGL +support. You will also need to install a TIFF library. Under Mandriva, you +would perform the following command: +<tscreen><verb> +# urpmi libtiff3-devel +</verb></tscreen> +Once you have satisfied the prerequisites for your distribution, install the application: +<tscreen><verb> +$ cd ~/mythplugins-0.21 +$ ./configure --disable-all --enable-opengl --enable-mythgallery +$ qmake mythplugins.pro +$ make +# su +# make install +# exit +$ +</verb></tscreen> +The configuration for MythGallery is accessed through the main Setup option +in mythfrontend. Make sure you set your pictures directory to wherever +you're storing your photos. + +The controls for MythGallery can be found in the README that comes with the +application. +<sect1>Using MythGallery +<p>When you first start MythGallery, you will see a thumbnail view of any +folders and pictures in the Gallery Directory you specified in setup. If +this is the first time you have accessed this directory, the thumbnails will +be generated on the fly. If the Gallery Dir is writable, these thumbnails +will be cached thus speeding up future access. On the left is a greyed-out +menu of options. + +Use the arrow keys to select a folder or picture to open/view with the +Select key, or use the Menu key to toggle access the menu on the left. The +menu options are as follows: +<itemize> +<item> Slideshow - Will cycle through all the pictures in the current folder. +The currently selected item must be a picture (not a folder) for this to +work. It does not currently traverse subfolders. +<item> Rotate CW - Rotate the current image 90 degrees in the clockwise +direction. This change persists if the current directory is writable. +<item> Rotate CCW - As above except the direction of rotation is counter(anti) +clockwise. +<item> Import - Import pictures into your Gallery Dir. This option is +described in the next section. +<item> Settings - Access the MythGallery settings screen. +</itemize> +<sect1>Importing Pictures +<p>The import path in the setup dialog is a colon separated list of +directories and/or executable files. When the import key is pressed, a new +directory (the destination directory) under the current directory will be +created and the import path will be searched. If the item in the import +path is a directory (the source directory), the contents of that directory +will be copied to the destination directory. If you would like the source +directory to be that of a removable device, it might be a good idea to use +autofs. See the automount howto at <url url="www.linuxdoc.org" +name="www.linuxdoc.org"> for info on how to get it working. + +If the item in the import path is an executable file, MythGallery will +attempt to execute it with the destination directory as its sole argument. +Be careful when using executable scripts that the script runs unattended +(doesn't need user intervention) and returns properly, otherwise it could +create the appearance of MythGallery hanging (e.g. running +<bf>smbclient</bf> and prompting for password). Also be sure that scripts +have executable permissions set. + +Here is an example script that a user may want to run +on import: +<tscreen><verb> +#!/bin/csh + +if ($#argv == 0) then + echo "Usage: $0 dest_dir" + exit +endif + +cd $argv[1] + +# get stuff over the network +wget http://www.somesite.dom/dir/file1.jpg +wget http://www.somesite.dom/dir/file2.jpg +wget http://www.somesite.dom/dir/file3.jpg + +# stuff that requires manual module loading and/or fs mounting +modprobe camera_module +mount /dev/camera /mnt/camera +cp /mnt/camera/* $argv[1] +umount /mnt/camera +rmmod camera_module + +# perform some processing +foreach pname (`ls *.jpg`) + jpegtran -flip vertical $pname > $pname.new + mv $pname.new $pname +end +</verb></tscreen> + +<sect>MythGame. +<!-- Install instructions by Hary Wilke (harywilke at yahoo.com --> +<p>MythGame can used as a frontend to start any emulator that your host OS +runs. This is an example of how to set up xmame on Linux. +<url url="http://www.mameworld.net/" name="http://www.mameworld.net/"> is +an excellent resource for all things mame. + +Installation overview: +<enum> +<item>Setup directory structure +<item>Download and install xmame +<item>Download and place extra files (artwork/catver.ini/etc..) +<item>Download and install MythGame plugin +<item>Setup xmame in MythGame +<item>Hints +</enum> +<sect1>Setup Directory Structure +<p>To keep things organized, create the following directories for <bf>xmame</bf> to use +in <tt>/usr/local/share/xmame</tt>: hiscore, roms, and snaps. + +<tscreen><verb> +$ mkdir -p /usr/local/share/xmame/{highscore,roms,snaps} +</verb></tscreen> + +<sect1>Download and Install xmame +<p><bf>NOTE</bf>: There may be pre-packaged versions of <bf>xmame</bf> +available for your distribution. Check <url +url="http://x.mame.net/download.html" +name="http://x.mame.net/download.html"> for the latest version. + +Download the source to <bf>xmame</bf> from <url +url="http://x.mame.net/download/xmame-0.103.tar.bz2" +name="http://x.mame.net/download/xmame-0.103.tar.bz2"> + +<tscreen><verb> +$ wget http://x.mame.net/download/xmame-0.103.tar.bz2 +$ tar -xjf xmame-0.103.tar.bz2 +$ cd xmame-0.103 +</verb></tscreen> + +Edit the Makefile with your favorite editor. Adjust the options as required for your system. +<tscreen><verb> +$ joe Makefile +</verb></tscreen> + +Then make and install xmame +<tscreen><verb> +$ make +$ su +(enter password) +# make install +# exit +</verb></tscreen> + +After <bf>mame</bf> has been installed, we need to create some defaults. +<tscreen><verb> +$ mkdir ~/.xmame +$ cp docs/xmamerc.dist ~/.xmame/xmamerc +</verb></tscreen> + +Because some ROMS work better with different display toolkits, or possibly +even older versions of xmame, it's convenient to keep all of your +<bf>xmame</bf> binaries and to rename them to include the version number. +MythGame allows you to match individual roms to preferred binaries. + +<tscreen><verb> +$ su +(enter password) +# mv /usr/local/bin/xmame.x11 /usr/local/bin/xmame-0.103.x11 +# exit +</verb></tscreen> + +<bf>NOTE</bf>: Depending on how you compiled <bf>xmame</bf>, you may have +<bf>xmame.X11</bf>, <bf>xmame.SDL</bf> or <bf>xmame.xgl</bf> based on what +display toolkit you used. Also, you may need to remove and recreate +<tt>xmamerc</tt> after upgrading since some of the default options may have +changed. + +Edit <tt>~/.xmame/xmamerc</tt> to include your paths. +<tscreen><verb> +### Fileio Related ### +rompath /usr/local/share/xmame/roms +snapshot_directory /usr/local/share/xmame/snaps +cheat_file /usr/local/share/xmame/cheat.dat +hiscore_file /usr/local/share/xmame/hiscore.dat +hiscore_directory /usr/local/share/xmame/hiscore +history_file /usr/local/share/xmame/history.dat +mameinfo_file /usr/local/share/xmame/mameinfo.dat +</verb></tscreen> + +Confirm that <bf>xmame</bf> works before running it inside MythTV. Place +your ROM in the <tt>/usr/local/share/xmame/roms</tt> directory you created +earlier. + +<bf>NOTE</bf>: There are three public domain ROM sets available at +<url url="http://www.mame.net/downmisc.html" name="http://www.mame.net/downmisc.html"> + +Launch <bf>xmame</bf> with your game of choice. In this example, we are using Gauntlet. +<tscreen><verb> +$ xmame gauntlet +</verb></tscreen> + +Some basic <bf>mame</bf> keyboard commands: +<tscreen><verb> +5 = Insert coin +1 = Player 1 start +arrow keys = movement +left control = button 1 +left alt = button 2 +SPACE = button 3 +ESC = exit +TAB - menu +~ to adjust Volume + < and > +</verb></tscreen> + +<sect1>Download extra files +<p>The following files allow you to add extra functionality. Place them +into <tt>/usr/local/share/xmame</tt> + +- <tt>catver.ini</tt> is a catalog of categories and versions of popular mame ROMs. +<p>Useful for keeping large libraries of ROMs organized. + +It may be downloaded from <url url="http://www.catver.com" +name="http://www.catver.com"> or <url url="http://www.mameworld.net/catlist" +name="http://www.mameworld.net/catlist"> + +- Screenshots aka "snaps" +<p>These may be downloaded from <url +url="http://www.classicgaming.com/mame32qa/" +name="http://www.classicgaming.com/mame32qa/"> + +Screenshots are displayed when you are browsing your ROMS in <bf>mythgame</bf>. +Unzip and place them in <tt>/usr/local/share/xmame/snaps</tt> + +- <tt>history.dat</tt> +<p>Download from <url url="http://www.arcade-history.com/" +name="http://www.arcade-history.com/"> +This file fills in a bit of background about each ROM. + +- <tt>hiscore.dat</tt> +<p>Download from <url url="http://www.mameworld.net/highscore/" +name="http://www.mameworld.net/highscore/"> + +- Cheats +<p>Download from <url url="http://cheat.retrogames.com/" +name="http://cheat.retrogames.com/"> + +<sect1>Download and Install MythGame. +<p><bf>MythGame</bf> is part of the mythplugins package. See the instructions +in the <ref id="DownloadAndCompile" name="Downloading and Compiling"> +section to obtain mythplugins. + +Switch to the mythplugins directory: +<tscreen><verb> +$ cd ~/mythplugins-0.21 +</verb></tscreen> + +Compile and install mythgame: +<tscreen><verb> +$ ./configure --disable-all --enable-mythgame +$ qmake mythplugins.pro +$ make +$ su +(enter password) +# make install +# exit +</verb></tscreen> + +<sect1>Setup xmame in MythGame +<p>Start <bf>mythfrontend</bf> and navigate to Utilities/Setup > Setup > Media +Settings > Game Settings > Game Players. Select <tt>(New Game Player)</tt>. + +To set up a new player for xmame enter the following: + +<tscreen><verb> +Player Name: xmame-0.103.x11 (Name by which you want your emulator or game called) +Type: xmame (This is used for display purposes only and does not affect the function of your system) +Command: xmame-0.103.x11 -vidmod 1 -fullscreen (Path and name of binary + any optional parameters) +Rom Path: /usr/local/share/xmame/roms (This tells MythGame what directories to scan for roms to be used with this emulator) +ScreenShots: /usr/local/share/xmame/snaps (This tells MythGame what directories to scan for snapshots to be used with these roms) +Working Directory: (Directory to change to before launching game or emulator. Blank in our case ignores this setting) +File Extensions: (List of all file extension to be used for this emulator. Blank menas any file under the Rom Path) +[] Allow games to span multiple roms/disks (will treat game.1.rom game.2.rom game.3.rom as one game) +</verb></tscreen> + +<sect1>Hints: +<p> +<itemize> +<item>Rom name before options: %s can be used as a standin for rom names on the command line. +<item>Multiple disk/rom games: %d1 %d2 etc can be used as standins for multiple disc games on the command line. +<item>Associating a rom with an emulator: Browse to the desired rom and press 'M' to enter the settings page for that rom. +<item>Assign a Game Favorite Status: Browse to the desired game and press "/". +</itemize> + +<sect>MythMusic. +<p>MythMusic has a number of prerequisites that must be satisfied before it +is operational. Depending on your distribution, some of these prerequisites can +be satisfied through the various package managers. If your distribution doesn't +offer pre-compiled versions of the software below, then follow the generic +instructions for manually compiling and installing the software. + +The prerequisites for MythMusic are: +<itemize> +<item>MAD +<item>taglib +<item>libogg and libvorbis +<item>FLAC +<item>libcdaudio +<item>CDParanoia +</itemize> + +<sect1>Manual installation of prerequisites +<p>These instructions are for distributions which don't have pre-compiled +versions of the software necessary to run MythTV. + +Download MAD from <url url="http://www.underbit.com/products/mad" +name="http://www.underbit.com/products/mad"> and install: + +<tscreen><verb> +$ tar -xzf mad-0.15.1b.tar.gz +$ cd mad-0.15.1b +$ ./configure +$ make +$ su +# make install +# exit +</verb></tscreen> + +Download TagLib from <url url="http://developer.kde.org/~wheeler/taglib.html" +name="http://developer.kde.org/~wheeler/taglib.html"> and install: + +<tscreen><verb> +$ tar -xzf taglib-1.4.tar.gz +$ cd taglib-1.4 +$ ./configure +$ make +$ su +# make install +# exit +</verb></tscreen> + +Download libogg and libvorbis from <url url="http://www.xiph.org/downloads" +name="http://www.xiph.org/downloads"> and install in a similar manner +to the above packages. + +Download FLAC from <url url="http://flac.sourceforge.net" +name="http://flac.sourceforge.net"> and install: +<tscreen><verb> +$ tar -xzf flac-1.1.2.tar.gz +$ cd flac-1.1.2 +$ ./configure +$ make +$ su +# make install +# exit +$ +</verb></tscreen> + +Download libcdaudio from <url name="http://libcdaudio.sourceforge.net" +url="http://sourceforge.net/project/showfiles.php?group_id=27134"> and +install: +<tscreen><verb> +$ tar -xzf libcdaudio-0.99.12p2.tar.gz +$ cd libcdaudio-0.99.12p2 +$ ./configure +$ make +$ su +# make install +# exit +$ +</verb></tscreen> + +Download cdparanoia from <url name="http://www.xiph.org/paranoia/down.html" +url="http://www.xiph.org/paranoia/download/cdparanoia-III-alpha9.8.src.tgz">. +<tscreen><verb> +$ tar -xzf cdparanoia-III-alpha9.8.src.tgz +$ cd cdparanoia-III-alpha9.8 +$ ./configure +$ make +$ su +# make install +# cd /usr/lib +# ln -sf libcdda_interface.so.0.9.8 libcdda_interface.so +# ln -sf libcdda_paranoia.so.0.9.8 libcdda_paranoia.so +# exit +$ +</verb></tscreen> + +<sect1>Mandriva +<p>Mandriva has a number of the prerequisites available on the +installation CD. Some of the software you're going to need will have to be +obtained from the "contrib" or "cooker" development repositories. +Applications downloaded from "cooker" come from the development branch, so +there may be issues with some software. It isn't recommended that you mix +cooker and release-level software. + +<p><bf>urpmi</bf> is the simplest tool for installation of packages from the +command line. The difficult part is the configuration, but this has been +made easier at the following website: <url +url="http://addmedia.linuxfornewbies.org/" +name="http://addmedia.linuxfornewbies.org/"> The website will allow +you to choose a mirror site and then present the command-line configuration +text for that mirror. You will most likely need to add a "Contrib" mirror +to your setup. Once you have done that, you can proceed. If <bf>urpmi</bf> +prompts you about other modules that need to be installed to satisfy +dependencies, say "Yes". + +<tscreen><verb> +# urpmi libmad0 libmad0-devel libflac4 libflac4-devel libcdaudio1 cdparanoia +# urpmi libcdda0 libcdda0-devel libvorbis0 libvorbis0-devel +# urpmi libcdaudio1-devel libid3tag0 libid3tag0-devel +</verb></tscreen> + +<sect2>Additional options with MythMusic +<p>Additional visualizations have been added to MythMusic. If you wish to +use these, there are some prerequisites you must install prior to compiling. + +<itemize> +<item>fftw +<item>OpenGL +<item>SDL +</itemize> + +<tt>fftw</tt> may be obtained from <url url="http://www.fftw.org/" +name="http://www.fftw.org/">. In Mandriva it may be installed by +typing: +<tscreen><verb> +# urpmi libfftw2 libfftw2-devel +</verb></tscreen> + +<tt>OpenGL</tt> should be installed on practically all distributions. +However, you will need the devel module. In Mandriva it may be +installed by typing: +<tscreen><verb> +# urpmi libMesaGLU1-devel +</verb></tscreen> + +<tt>SDL</tt> may be obtained from <url url="http://www.libsdl.org" +name="http://www.libsdl.org">. In Mandriva it may be installed by +typing: +<tscreen><verb> +# urpmi libSDL1.2 libSDL1.2-devel +</verb></tscreen> + +<sect1>Red Hat Linux 9 +<p>Red Hat provides packages for several of the prerequisites, making +installation very simple. Of the prerequisites, Red Hat provides +packages for Vorbis, cdparanoia, SDL, and OpenGL (which you probably +already have installed). To install these all at once, simply type (all on +the same line): +<tscreen><verb> +$ up2date --solvedeps libvorbis libvorbis-devel vorbis-tools cdparanoia-devel cdparanoia-libs cdparanoia SDL-devel SDL +</verb></tscreen> + +If you get the following message: "None of the packages you requested +were found, or they are already updated" it probably means you already +have all of those packages installed. + +You must install the remaining packages, (MAD, FLAC, libcdaudio and +optionally fftw) manually following the installation directions above. When +installing fftw do not use the rpm package offered on the website because it +will cause an error, so use the source package instead. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: you can use the instructions given at the <ref id="atrpms" +name="automated installation section"> to install all of MythMusic in one +step. +</caption> +</figure> +<sect1>Compiling MythMusic +<p>Once all the prerequisites have been installed, you can proceed with +compiling MythMusic. + +<tscreen><verb> +$ cd ~/mythplugins-0.21 +$ ./configure --disable-all --enable-mythmusic --enable-fftw --enable-sdl --enable-aac +$ qmake mythplugins.pro +$ make +$ su +# make install +# exit +</verb></tscreen> + +<sect1>Configuring MythMusic +<p>Configuration of MythMusic occurs in two places. The main mythfrontend +Setup is for global MythMusic configuration. Go to the +Setup/MythMusic/General Setup screen and adjust it for your particular +configuration. + +The second configuration screen is within the MythMusic program and will +allow you rescan your music library, etc. + +Here's some explanation about the Ignore_ID3 and The NonID3FileNameFormat: + +If Ignore_ID3 is set to TRUE, MythMusic will try to determine the +Genre, Artist, Album, Track Number, and Title from the filename of the +mp3 file. The NonID3FileNameFormat variable should be set to the +directory/file format where the mp3 files are stored. For instance, I +store mine in the above shown Genre/Artist/Album/Track format. MythMusic +will then use this information to fill in the proper fields when it +populates the musicmetadata table rather than searching for an ID3 tag in +the mp3 file. + +The files can be laid out in any format, such as: + +Genre/Artist/Album/Title +Artist/Genre/Album/Title +Artist/Album/Title (with Genre left as Unknown) + +The track number is optional but can be specified with the title by using +the TRACK_TITLE keyword instead of TITLE. If TRACK_TITLE is used, +then the filename can have a space, hyphen, or underscore separating the +track number from the track title. Keywords are case insensitive, so if +you specify GENRE it's the same as Genre in the format field. + +The Ignore_ID3 option does not disable the code that determines the track +length, just the portion that tries to read ID3 info. + +<sect1>Using MythMusic +<p>MythMusic is fairly simple to use. It is recommended that you insert the +CD before selecting "Import CD". You should also ensure that your system +doesn't try to automount the CD and begin playing it automatically. + +<!-- +Next stuff is from a message by jasonmiller [jasonmiller@micron.com] +with additional comments by Thor +--> +Here's some information on playlist management: + +Q: How do I create a new playlist? +A: Using the MythMusic "Select Music" menu option, setup the playlist as you +normally would by adding songs or other playlists as needed. When you are +ready to save the new playlist, highlight "Active Play Queue" at the bottom +of the selection tree and hit the "i" key. This will pop up a menu allowing +you to name and save the new playlist. You can also hit Enter to bring up +the popup on the Active Play Queue. This does not work on the playlists +above, as Enter is obviously bound to checking/unchecking the boxes. Any +number (i.e. keypad on remote) will also bring up the menu in both cases. + +Q: How do I enter the playlist name in the text field without a keyboard? +A: Use the keypad number keys (bound to your remote) to select letters +quasi-cell phone style. Keys 2-9 work pretty much like any cell phone text +entry. 1 cycles through a few special characters, delete, and space. 0 is +like a CAPS LOCK. Hard to describe, fairly easy to use. You will soon be +able to specify the cycle timing in a Setup screen. You can type fairly +quickly through a combination of jumping around the number keys AND hitting +a non-number key (right arrow is particularly good for this) to force the +current character. + +Q: How do I edit a playlist? +A: Highlight the playlist in the selection tree and hit the "i" key then +select "Move to Active Play Queue" in the popup. You can now modify the +"Active Play Queue" like normal, adding songs and playlists by selecting +them from the song tree. When you are done, highlight the "Active Play +Queue" in the selection tree and hit the "i" key then select "Save Back to +Playlist Tree". And whatever you were editing as your Active Queue before +you moved an existing playlist "on top" of Active reappears. Think of Active +has having a push on, pop off capability, but with a depth of only 1. + +Q: How do I delete an item from a playlist? +A: Highlight the item in the selection tree and hit the "d" key. + +Q: How do I rearrange the songs in my playlist? +A: Highlight a song and hit the "space" bar, the song will now have pair of +red arrows in front of it. Use the up and down arrow keys to move it around +in the playlist. When you have it where you want it, hit the "space" bar +again. + +Q: How do I delete a playlist? +A: Highlight the playlist in the selection tree and hit the "i" key then +select "Delete this Playlist" from the popup. + +<sect1>Troubleshooting MythMusic +<p>You may run into errors when running MythMusic. +<sect2>When I run MythMusic and try and look up a CD, I get an error message +<p>The full text of the message will say: + +databasebox.o: Couldn't find your CD. It may not be in the freedb database. +More likely, however, is that you need to delete ~/.cddb and ~/.cdserverrc +and restart mythmusic. Have a nice day. + +If you get this message, you should go to the home directory of whatever +user MythMusic is running as and type: +<tscreen><verb> +rm .cdserverrc +rm -rf .cddb/ +</verb></tscreen> + +These files aren't automatically deleted because of a conscious design +decision by the author that programs that automatically delete things are +bad. + +The files are used to locally cache CD lookups. If you are re-inserting +CDs, your machine will not actually have to go out to the Internet to +determine what is on them. However, the URL used to access the freedb +database has recently changed, so the stale information in the files from +previous runs of MythMusic would cause the error above. Once the files have +been deleted the stale information will be gone and your local database +will be rebuilt as you use CDs. + +<sect>MythWeather. +<p> +MythWeather is a part of the <bf>mythplugins</bf> package. See <ref +id="mythplugins_" name="MythPlugins"> for instructions on downloading the +tarball. + +<tscreen><verb> +$ cd ~/mythplugins-0.21 +$ ./configure --disable-all --enable-mythweather +$ qmake mythplugins.pro +$ make +$ su +# make install +# exit +</verb></tscreen> + +MythWeather uses MSNBC.com as its source for weather data and weather.com +for its radar image. + +These are the keyboard commands for MythWeather: +<tscreen><verb> +Left Key Goes back one page, and extends the time spent + on the page you are on. +Right Key Goes forward one page, see above. +Space Pause, wait on the current page until space is hit + again. +Numeric Keys You can check other weather by keying in other ZIP codes. +Enter Key Switch between Celsius and Fahrenheit. Can also + be used a way to force a data update. +"m" Key Resets the location to the database default, then updates the data. +"i" Enter / Save settings +ESC Exit the settings screen without saving / Exit the program +</verb></tscreen> + +MythWeather also has an "Aggressiveness" setting. This affects how long +MythWeather waits for data from the msnbc.com website before timing out. If +you are on a slow connection, or have a slow DNS, or MythWeather just +doesn't seem to be working and you've already tried everything else, then +try increasing the aggressiveness level parameter. This parameter is +inverse; a higher number actually means that MythWeather will be less +aggressive, and will therefore wait longer before timing out. + +MythWeather will print debugging information on the terminal. If you wish +to see additional debugging information while MythWeather is running, run +mythweather from the command line with as <tt>mythweather --debug</tt> + +You may also force mythweather to re-run the configuration by starting it on +the command line as <tt>mythweather --configure</tt>. These two options are +mutually exclusive. + +<sect>MythVideo. +<p>MythVideo is a part of the <bf>mythplugins</bf> package. See <ref +id="mythplugins_" name="MythPlugins"> for instructions on downloading the +tarball. + +MythVideo will allow you to use an external program to watch media files +that are not directly supported by MythTV. + +<tscreen><verb> +$ cd ~/mythplugins-0.21 +$ ./configure --disable-all --enable-mythvideo +$ qmake mythplugins.pro +$ make +$ su +# make install +# exit +</verb></tscreen> + +See MythVideo's <tt>README</tt> file for additional information. + +<sect>MythDVD. +<p>MythDVD is a part of the <bf>mythplugins</bf> package. See <ref +id="mythplugins_" name="MythPlugins"> for instructions on downloading the +tarball. MythDVD is an application which rips DVDs and makes them available for +use with MythVideo. You may also transcode the DVD content from MPEG-2 to +other formats which should greatly reduce the amount of space the DVD +material takes up on your hard drive. + +MythDVD has a number of prerequisites to enable transcoding functionality. +If you only wish to play DVDs rather than convert them to something like +MPEG-4 or xvid you may skip the prerequisite installation step. + +<sect1>Manual Compilation of Prerequisites +<p> +<sect1>Pre-compiled binaries +<p>Mandriva users may install the prerequisites this way: +<tscreen><verb> +# urpmi libdvdread3 libdvdread3-devel a52dec liba52dec-devel +# urpmi mplayer ogle xine +</verb></tscreen> +Assuming that you've added a PLF mirror, you may also load the rest of the +prerequisites using the following command: +<tscreen><verb> +# urpmi xvid xvid-devel fame libfame0.9-devel transcode libdvdcss +</verb></tscreen> + +In the example below, we have enabled support for transcoding and for VCD +playing. You may remove these options if you don't need them. +<tscreen><verb> +$ cd ~/mythplugins-0.20 +$ ./configure --disable-all --enable-mythdvd --enable-transcode --enable-vcd +$ qmake mythplugins.pro +$ make +$ su +# make install +</verb></tscreen> +<sect1>Running the Myth Transcoding Daemon +<p>Transcoding ("ripping") a DVD requires you to run the Myth Transcoding +Daemon (mtd). To ensure that mtd is configured correctly, you should first +test it at the command line. +<tscreen><verb> +$ mtd -n +</verb></tscreen> +The last line of text should show something like: +<tscreen><verb> +mtd is listening on port 2342 +</verb></tscreen> +This indicates that mtd is ready for use. Once you've successfully +tested mtd in the foreground, type <bf>CTRL-C</bf> to stop mtd. You may +then start it as a background (daemon) process. +<tscreen><verb> +$ mtd -d +</verb></tscreen> + +Running mtd as a daemon will allow you to automatically start it during the +boot process. For example, you may add <tt>mtd -d</tt> to your +<tt>rc.local</tt> file, or you can adjust the script/steps outlined in the +section called <ref id="mythbackend_autostart" name="Automatically starting +mythbackend at system boot time"> to start mtd instead of mythbackend. + +<sect>MythNews. +<p>MythNews is a part of the <bf>mythplugins</bf> package. See <ref +id="mythplugins_" name="MythPlugins"> for instructions on downloading the +tarball. MythNews is a RSS reader. +<tscreen><verb> +$ cd ~/mythplugins-0.21 +$ ./configure --disable-all --enable-mythnews +$ qmake mythplugins.pro +$ make +$ su +# make install +</verb></tscreen> + +<sect>Troubleshooting. +<sect1>Compiling +<sect2>Compile errors +<p>Some compile errors are worse than others. If you get an error that +doesn't abort the compilation, and says something like: +<tscreen><verb> +cc1plus: warning: changing search order for system directory +"/usr/local/include" +cc1plus: warning: as it has already been specified as a non-system +directory +</verb></tscreen> +then it shouldn't be a problem. + +If you get an error like <tt>/usr/bin/ld: cannot find -lXext</tt>, the +compiler is telling you that you don't have XFree86-devel installed, or that +your distribution hasn't set it up correctly. This needs to be fixed before +MythTV will compile. + +<sect2>make: *** No rule to make target /usr/lib/qt3/mkspecs/default/qmake.conf', needed by Makefile'. Stop. +<label id="mkspecs_error"> +<p>This error happens when there's a missing link in the +<tt>/usr/lib/qt3/mkspecs</tt> directory. There are two ways to fix this +error: + +1. Create the link manually: +<tscreen><verb> +$ su +# cd /usr/lib/qt3/mkspecs +# ln -sf linux-g++ default +</verb></tscreen> +and then restart the compile, + +or + +2. Run <bf>qmake mythtv.pro</bf> in the mythtv directory. Rerunning +<bf>qmake</bf> will create a new Makefile for you, however this still +doesn't fix the root cause of the issue, which is that your distribution +didn't create the symlink for you when the qt3 package was installed. The +first choice is the better solution. + +<sect2>make: *** No rule to make target /mkspecs/default/qmake.conf', needed by Makefile'. Stop. +<p>You didn't set your <tt>QTDIR</tt>. Re-read the section on <ref +id="Setting_up_paths" name="Setting up paths">. + +<sect2>Internal Segmentation Fault. +<p>This is most likely to be caused by an overheating processor rather than +an actual programming fault within gcc. + +<sect1>Debugging <label id="debugging"> +<sect2>MythTV segfaults +<sect2>MythTV isn't doing anything +<sect2>Debugging with GDB +<p>Without details, the developers will not be able to determine if you have +discovered a genuine code-bug, or if the problem is with your system. In +order to determine what's going on, you must recompile MythTV with debugging +support and run MythTV within <bf>gdb</bf>, the GNU debugger. +Note that, on OS X, some data is provided without going through these steps. +See ~/Library/Logs/CrashReporter/MythFrontend.crash.log + +Re-run the <bf>configure</bf> script and add <tt>--compile-type=debug</tt> +to any previous configuration options you may have used. Check the +<tt>config.log</tt> file if you have forgotten. + +Now, you need to clear out the old versions of the software to ensure that +you're running with the debugging code, then compile and install. +<tscreen><verb> +$ make distclean +$ ./configure --compile-type=debug +$ make +$ su +# make install +# exit +</verb></tscreen> + +At this point, you now have debug-enabled software ready. To make sure that +you don't forget to type a command required for debugging, it's best to +setup a <tt>gdbcommands</tt> file. This will be read by <bf>gdb</bf> when it's +started. +Put the following into <tt>gdbcommands</tt> in your home directory: + +<tscreen><verb> +handle SIGPIPE nostop noprint +handle SIG33 nostop noprint +set logging on +set pagination off +set args -l myth.log -v record,channel,siparser +run +thread apply all bt full +set logging off +</verb></tscreen> + +Let's assume that the problem you're having is in <bf>mythbackend</bf>. + +<tscreen><verb> +$ gdb mythbackend -x gdbcommands +GNU gdb 6.3-debian +Copyright 2004 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, and you are +welcome to change it and/or distribute copies of it under certain conditions. +Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" for details. +This GDB was configured as "i386-linux".Using host libthread_db library "/lib/tls/libthread_db.so.1". +[Thread debugging using libthread_db enabled] +</verb></tscreen> + +<bf>gdb</bf> will automatically read the commands that you've placed in the +<tt>gdbcommands</tt> file and begin running the program you specified on the +command line. + +If the program appears to be locked up, press CTRL-C to create the backtrace +file. + +All of the output from <tt>gdb.txt</tt> should be posted to the mythtv-dev +mailing list, along with the steps you followed to get the program to crash. + +<bf>NOTE</bf>: If you're trimming the <tt>gdb.txt</tt> file to remove +extraneous information from the beginning of the file, make sure you include +at least 10 lines <em>prior</em> to the point where the backtrace actually +begins. This ensures that there is some context to the backtrace, and so +that it's possible to see what exactly caused the segfault. + +<bf>gdb</bf> has a number of options, read the <tt>man</tt> page for more +information. + +Using the <tt>gdbcommands</tt> file in conjunction with a <bf>while</bf> loop +will ensure that <bf>gdb</bf> creates a trace file and then restarts: + +<tscreen><verb> +$ while true; do date >> gdb.txt; gdb mythbackend -x gdbcommands; done; +</verb></tscreen> + +<bf>NOTE</bf>: To exit this loop you will need to kill the while loop. + +If you're trying to troubleshoot and you can't get back to the <bf>gdb</bf> window +for some reason, it may be easier to use two systems or to start +mythfrontend from the text console. + +If you're going to troubleshoot from a remote system, connect to the machine +that you're going to test using <bf/ssh</> or <bf>telnet</bf>. Next, type +<tt>$ export DISPLAY=localhost:0.0</tt>. This will allow the graphics to be +displayed on the X console (usually ALT-F6 or ALT-F7) and still give you +output and control of <bf>mythfrontend</bf>, either from the <bf>ssh</bf> +session, or by switching back to the text console by pressing CTRL-ALT-F1. +You can now continue troubleshooting using <bf>gdb</bf> as detailed in the +instructions. + +<sect2>MythTV is crashing your system +<p>When run as a non-privileged user, MythTV <em>can not</em> crash your +system. If your system is crashing when you run MythTV, then you have some +issue with the drivers for your capture card or other hardware, or the CPU +fan has fallen off/broken and your system is overheating when asked to +perform a CPU intensive task like encoding video. + +If you are running as root, which is <bf>strongly discouraged</bf>, it is +possible that your system may crash due to the real-time thread using all +available CPU. You will not be able to interrupt the process, so for all +intents and purposes your computer will have crashed. + +<sect1>Installing +<sect2>When trying to run mythtv-setup, you get an error like this: +"mythtv-setup: error while loading shared libraries:" +<p>You didn't add <tt>/usr/local/lib</tt> to <tt>/etc/ld.so.conf</tt>. See the +section on modifying <ref id="modifying_ld.so.conf" name="/etc/ld.so.conf">. + +<sect1>Using +<sect2>No programs are displayed in "Watch Recordings" +<p>This situation occurs most often with a system that acts as a frontend +and a slave backend. MythTV supports system-global and user-specific +configuration files, with user-configuration files taking precedence. 99% +of the configuration for MythTV is in the MySQL database, but MythTV still +needs to know where the MySQL server is running. This information is in the +<tt>mysql.txt</tt> file. By default, it will be installed to +<tt>/usr/local/share/mythtv</tt>, but a copy placed into <tt>~/.mythtv</tt> +will over-ride the global configuration. + +You must ensure that there aren't multiple, conflicting versions of this +file on your system! +<tscreen><verb> +$ locate mysql.txt +/usr/local/share/mythtv/mysql.txt +/home/mythtv/.mythtv/mysql.txt +$ +</verb></tscreen> + +As you can see, in this example there are two <tt>mysql.txt</tt> files. If +they are not identical, then there may be unintended consequences. + +You may also see this error if you completely fill the <tt>/var</tt> +partition. The most likely <em>mythtv-related</em> reason for this is an +overly large mythbackend or mythfrontend log file in <tt>/var/log</tt>. If +you have logging enabled for the backend, and myth runs for weeks at a time, +this may creep up and surprise you. Note that many system processes also +write to <tt>/var</tt> and the system may not boot if it is unable to write +to <tt>/var</tt> due to a full partition. + +<sect2>MySQL not connecting correctly +<p>Your <bf>MySQL</bf> installation may have networking turned off. +Check that <tt>/etc/mysql/my.cnf</tt> <em>does not</em> contain +<tt>skip-networking</tt>. If it does, remove it. Also verify that +<tt>bind-address</tt> is set to your IP address instead of +<tt>127.0.0.1</tt>. If you change either of these items, restart +<bf>MySQL</bf>. + +<sect2>MySQL database is corrupt +<p>If you have reason to believe that your MySQL database is corrupt, +execute the following commands to attempt to repair it. + +<bf>NOTE</bf>: Ensure that there are no programs accessing the database +while you attempt to repair it. Make sure that all backend and frontend +programs have exited. + +<tt>mysqlcheck -r -umythtv -p<password> mythconverg</tt> + +<sect2>Using a MPEG-2 encoder card and the video appears "jittery" +<sect2>Using a MPEG-2 encoder card and the video is jumping up and down +<p>This is a different problem than the one discussed in the previous +section. Currently, the ivtv driver or firmware appear to have some issues +if the vertical capture resolution is not the full screen height. If you +are having a jitter problem then ensure that you are capturing either 480 +lines (for NTSC) or 576 lines (for PAL). The default capture profiles may +need to be edited for your setup. Go to Settings->TV Settings->Recording +Profiles and adjust the <bf>Default</bf> and <bf>Live TV</bf> options to +480 or 576 from their defaults. + +<sect2>Screen goes blank but returns when mouse is moved or keyboard is used +<p>This is due to DPMS, the Display Power Management System, which is used +to save power by turning off your monitor when the system decides that it's +not being used or due to a screensaver that has defaulted to a blank screen. +MythTV now has DPMS support built-in, and should intelligently handle the +screen. Continue reading if you wish to override DPMS and force it off. + +Since it's likely that watching TV will not generate keyboard or mouse +events for a time, you need to turn off DPMS and the screensaver. There are +a few ways to do this. You may also need to check your BIOS for power +saving modes and disable screen blanking there as well. + +Edit your <tt>/etc/X11/XF86Config-4</tt> or <tt>/etc/X11/xorg.conf</tt> +file, and look for: +<tscreen><verb> +Section "ServerFlags" + #DontZap # disable <Ctrl><Alt><BS> (server abort) + #DontZoom # disable <Ctrl><Alt><KP_+>/<KP_-> (resolution switching) + AllowMouseOpenFail # allows the server to start up even if the mouse doesn't work + + Option "blank time" "0" + Option "standby time" "0" + Option "suspend time" "0" + Option "off time" "0" + Option "NoPM" "1" +EndSection +</verb></tscreen> + +Also, look for: +<tscreen><verb> +Section "Device" + Identifier "device1" + VendorName "nVidia Corporation" + BoardName "NVIDIA GeForce 256 (generic)" + Driver "nv" + Option "DPMS" +EndSection +</verb></tscreen> + +In this case, you would need to either delete the <tt>Option "DPMS"</tt> +line, or change it to <tt># Option "DPMS"</tt> to comment it out. The next +time you start XFree this change will take effect. + +Finally, check: +<tscreen><verb> +Section "Monitor" + Identifier "monitor1" + VendorName "Plug'n Play" + HorizSync 30-85 + VertRefresh 50-160 + + # Sony Vaio C1(X,XS,VE,VN)? + # 1024x480 @ 85.6 Hz, 48 kHz hsync + ModeLine "1024x480" 65.00 1024 1032 1176 1344 480 488 494 563 -hsync -vsync + + # TV fullscreen mode or DVD fullscreen output. + # 768x576 @ 79 Hz, 50 kHz hsync + ModeLine "768x576" 50.00 768 832 846 1000 576 590 595 630 + + # 768x576 @ 100 Hz, 61.6 kHz hsync + ModeLine "768x576" 63.07 768 800 960 1024 576 578 590 616 +EndSection +</verb></tscreen> + +Ensure that there isn't an <tt>Option "DPMS"</tt> in the Monitor +configuration. + +You can also turn off DPMS from the Command Line, but this will not survive +a reboot. +<tscreen><verb> +$ xset -dpms +</verb></tscreen> + +Using <tt>xset +dpms</tt> will turn it back on. + +Another technique to try, which will turn off the screensaver: +<tscreen><verb> +$ xset s off +</verb></tscreen> +You may also combine the command to turn off DPMS and the screensaver: +<tscreen><verb> +$ xset -dpms s off +</verb></tscreen> + +Finally, depending on your distribution, you may be able to turn it off from +within the control panel. +<sect1>Miscellaneous +<sect2>mythfilldatabase failing +<p>If mythfilldatabase suddenly appears to be failing, there are at least +two things to check. + +First, if you are in North America, ensure that your DataDirect subscription +is still valid, otherwise, check to see what version of XMLTV you're +running and that it's the latest version. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: It is highly recommended that you run the latest +version of XMLTV available. Your listings provider may have made changes +which negatively impact XMLTV. +</caption> +</figure> + +<sect2>Fast CPU, choppy or jittery video <label id="Setting_DMA"> +<p>First, you should check that your kernel has been enabled for DMA: +<tscreen><verb> +[mythtv@pvr mythtv]$ dmesg |grep DMA + ide0: BM-DMA at 0xd800-0xd807, BIOS settings: hda:DMA, hdb:DMA + ide1: BM-DMA at 0xd808-0xd80f, BIOS settings: hdc:DMA, hdd:pio +hda: 156301488 sectors (80026 MB) w/2048KiB Cache, CHS=9729/255/63, UDMA(33) +hdb: 80043264 sectors (40982 MB) w/2048KiB Cache, CHS=4982/255/63, UDMA(33) +</verb></tscreen> + +From the listing above, you can see that hda, hdb and hdc are set for DMA, +and hdd is set for pio. If your kernel is not reporting DMA being enabled, +you may need to recompile your kernel. Check your motherboard's chipset +(look in the "ATA/IDE/MFM/RLL support" section in "make menuconfig") for more +information. + +Next, check that the hard drive has DMA enabled. Use the <bf>hdparm</bf> +program to check and enable DMA. +<tscreen><verb> +# hdparm -d /dev/hd? +</verb></tscreen> will tell you the DMA status for your hard drives. If you run +<bf>hdparm</bf> with the <tt>-d1</tt> parameter, it will turn DMA on. + +<!-- Next section adopted from a post by Dwaine Garden +dwainegarden@rogers.com to the mailing list. --> + +You may also setup your PC to do this at boot time, either by adding the +command to your <tt>/etc/rc.local</tt> file, or by adding files to +/etc/sysconfig. + +On Mandriva and other distributions, if you install <bf>hdparm</bf> from an RPM you +will most likely get a <tt>/etc/sysconfig/harddisks</tt> file installed. +This file will be parsed by the <tt>/etc/rc.sysinit</tt> script. If you use +the default <tt>harddisks</tt> file, your changes will affect all IDE devices +(including CD ROMs). If you wish to use different parameters for various +devices, rename and/or copy the file to <tt>harddiskhda</tt>, +<tt>harddiskhdb</tt>, etc. Edit the file to your liking and on the next +reboot your setting will be preserved. + +<sect2>Frontend appears to be slow at jumping / seeking. +<sect2>On-screen Display shows incorrect program length. +<p>This may occur when MythTV doesn't have an accurate seek table. Run +<bf>mythcommflag --rebuild</bf> + +<sect2>Troubleshooting audio <label id="Troubleshooting_Audio"> +<!-- By Bruce Markey --> +<p> +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: the following instructions do not apply to PVR-250/350 +encoders; the MPEG-2 file will have the audio embedded in the stream so it +is not accessible using <tt>/dev/dsp</tt>. +</caption> +</figure> + +Audio appears to be one of the bigger issues that users run into on the +mailing list. If the audio isn't configured correctly, then MythTV will +often appear to hang, when in fact it is trying to manipulate the audio +subsystem and failing. You may or may not receive error messages indicating +that the source of the error is the audio subsystem. + +You can not use <bf>xawtv</bf> to determine if your audio is working +correctly, since <bf>xawtv</bf> is simply using the analog sound patched +through line-in to line-out. It doesn't need to digitize the sound unless +you are using the recording function. + +A better test to verify that sound will work for MythTV (and recording with +<bf>xawtv</bf> for that matter) is to startup <bf>xawtv</bf>, mute the +line-in then run <tt>aplay /dev/dsp</tt>. You should hear the recorded audio +slightly delayed behind the real-time video. You should see messages about +"underrun". These can be ignored but they do confirm that the driver is +loaded and there is an active device. Once this test succeeds, MythTV +should work correctly because it writes to and read from /dev/dsp in +the same way that <bf>aplay</bf> does. + +To record audio along with video the audio signal must be digitized by a DSP +so that the audio data can be stored in a file. On playback, the audio data +is written to /dev/dsp and converted back to an analog signal. This analog +signal should then be sent to your speakers. Here is what is needed in +<bf>alsamixer</bf>. If you are using an ALSA version after 1.0.6, use +<bf>alsamixer -V all</bf>: + +CAPTUR source - the analog source to be sent to the DSP. This should be set +to the input source from the tuner card to the sound card. In most cases +this is Line but this could also be Aux, CD, Mic, etc., depending on how you +connect the input cable. This source should be muted to prevent patching +through the analog sound. The volume of this source will not affect the +record level. + +Capture mixer - this sets the level for the analog to digital recording. +While a volume of 100% is recommended for testing, distortion may occur. +Lowering this level to 75% to 85% may result in better audio quality. +"Capture" should be marked as the CAPTUR destination. + +PCM mixer - this sets the level for the digital to analog playback. While a +volume of 100% is recommended for testing, distortion may occur. Lowering +this level to 75% to 85% may result in better audio quality. + +Master mixer - sets the level for the analog signal sent to line-out or the +speakers. + +You may also want to ensure that <tt>/dev/dsp</tt> , or whatever device file +is being used, hasn't already been grabbed by another process, like +<bf>esd</bf> or <bf>artsd</bf>. If the device file isn't available, then +MythTV won't work. You may wish to run <bf>configure</bf> and enable +support for these. + +If you wish to see what application is grabbing a resource, you can use the +<tt>fuser</tt> command: +<tscreen><verb> +# fuser -v /dev/dsp +</verb></tscreen> + +To disable aRts in KDE, go to KDE->Control Center->Sound->Sound System and +uncheck the "Start aRts soundserver on KDE startup" box. Run <tt># killall +artsd</tt> from the command line to stop the artsd program. + +If you're using multiple sound cards and multiple tuners, use <tt>alsamixer +-c 1</tt> to work with the second sound card. The first card is #0, the +second card is #1, etc. + +<sect2>Mythbackend reports that your card is not reporting full duplex capabilities +<sect2>The mythbackend program told me to look at this section +<p>mythbackend does a check to see if your sound device is capable of full +duplex operation. If it's not, it's most likely that you're going to run +into issues when you try to record and play sound at the same time. If your +backend is a separate machine than your frontend, then there's no problem, +since you're only going to be doing one thing at a time with the card. +Likewise, if you're running the frontend and backend on the same machine, +but you're using btaudio or a hardware encoder card such as the Hauppauge +PVR-250, DVB cards or HDTV capture cards as your recording source and you're +only using the playback function of your sound card, then you also shouldn't +have an issue, since the sound card isn't being asked to perform two +functions at once. + +If you can't get your sound card to go full-duplex and need it to, then check +your distribution for updated sound drivers. If your sound card is not +capable of full-duplex operation, either because the drivers don't support +it, or it has been designed that way, then you're pretty much out of luck +and will either need to purchase a new sound card, or will need to get +btaudio <ref id="btaudio" name="operational">. + +<sect2>My remote doesn't work / works sometimes and not others / "ghost" keypresses +<p>This can be due to a number of factors. The simplest case is the +"ghost" keypresses. For me, it was due to compact fluorescent lights in +the same room as the IR receiver, which the receiver was picking up as +keypresses. Once the lights were switched to incandescent bulbs, the ghost +went away. + +You may have an issue with <bf>lirc</bf> misinterpreting IR commands from a +different remote. I also have an issue where the TiVo "Peanut" remote will +eventually cause <bf>lircd</bf> to stop responding; even though <bf>lircd</bf> +is configured for the Pinnacle Systems remote, the TiVo remote IR patterns +are being seen by the IR receiver. + +If your remote has been properly configured, and <bf>irw</bf> and +<bf>irxevent</bf> are working correctly, then it's highly likely that your +window manager is not giving focus correctly to the various Myth programs as +they run. The following window managers are known to work correctly: + +<itemize> +<item>fvwm +<item>blackbox (using "Sloppy Focus" and "Focus New Windows") +</itemize> + +<bf>NOTE</bf>: You do not need to use <bf>irxevent</bf> if you are using +MythTV's native LIRC support, so the window manager focus issue does not +apply in that case. + +<sect2>Where's "canada-cable"? +<sect2>Channels are off by one +<p>There is no such thing as "Canada Cable"; Canada uses the same +frequencies as the United States. "Canada Cable" was a hack that some +people used when they would discover that their channels were off-by-one, +i.e. when tuning to channel 42, they might get channel 41 or 43. This is +actually due to the tuner on the video capture device being mis-detected. +You must manually specify the tuner type in your <tt>/etc/modules.conf</tt>. +See the video4linux mailing list (<url +url="https://listman.redhat.com/mailman/listinfo/video4linux-list" +name="https://listman.redhat.com/mailman/listinfo/video4linux-list">) for +more information. + +<sect2>Mythweb is showing a db_open error when I connect to it +<!-- Fix by Chris Ripp [chris@ripp.net] post to mailing list --> +<p>Find your <tt>php.ini</tt> file. Make sure you've got a line in it like this: + +<tt>extension=mysql.so</tt> + +Restart <bf>apache</bf> for it to take effect. + +<sect2>Mouse pointer disappears when placed over the MythTV windows +<p>This is the intended behavior. The MythTV interface is meant for use +with a remote control or a keyboard. + +<sect2>What does "strange error flushing buffer" mean on the console? +<p>Nothing, really. It's just lame (the mp3 encoder) complaining for some +obscure reason. This seems to be fixed in more recent versions of the +libmp3lame library. + +<sect2>Can't change the channel when watching Live TV. +<p>Something's wrong with your program database. Did mythfilldatabase run +with no major errors? Or, MythTV may not have permissions to the +appropriate video4linux devices. See the section titled <ref id="devperms" +name="Device Permissions"> for an example. + +<sect2>Screen goes black when you try to play something +<p>MythTV prints error and status messages to the shell that was used to +start the application. If nothing seems to be happening when you try to +view a program, try switching back to the shell and look for error messages +there, or, if you're running from a startup script, check the log file. + +<sect2>Poor performance with NVidia cards and XvMC +<p>XvMC is a NVidia driver feature which is supposed to help with decoding +video. Users have reported that rather than speeding up their video it +appears to be doing the opposite. You may want to check that your color +depth is set for 24bpp. + +<sect2>Computer is loading a media player application when you insert a CD or DVD +<p>You need to disable any sort of auto-running media player in your +environment, otherwise MythDVD or MythMusic will not be able to work +properly. + +In KDE, you may want to perform the following: +<tscreen><verb> +$ rm ~/.kde/Autostart/Autorun.desktop +</verb></tscreen> +<sect>Miscellaneous. +<sect1>I'd like to watch the files without using MythTV / I'd like to convert the files to some other format +<p>First, check if the <bf>mytharchive</bf> plugin does what you want. If not, then +read on: + +MythTV comes with a utility called <bf>mythtranscode</bf> which can +decode nuv files into raw format for use with other applications. This +command-line utility was not designed to be used by the end-user, but +instead to be called by other applications or scripts. Programs like +<bf>nuvexport</bf> (<url url="http://forevermore.net/myth/" +name="http://forevermore.net/myth/">) are better suited for the end user. +However, since <bf>mythtranscode</bf> can be a useful tool, directions on +using it follow. + +<bf>mythtranscode</bf> creates raw streams, which means that they do not +contain any container information such as resolution, frame-rate, or audio +sampling rate. In order to process the output, you must supply this +information to the processing utility. <bf>mythtranscode</bf> provides the +relevant information on STDOUT. + +There are two modes in which <bf>mythtranscode</bf> can create raw streams. +The first has no synchronization and assumes that the processing utility +will read audio and video at a constant rate. This method is useful when a +single application will be processing the raw output, such as +<bf>mencoder</bf> or <bf>ffmpeg</bf>. The second method assumes that two +separate applications will be processing the audio and video streams +independently, and there is no rate control between them which means that +the two programs don't coordinate their efforts to maintain synchronization. + +<sect2>mythtranscode example +<p>First, start <bf>mythtranscode</bf>. You will need to determine the +channel and the start time manually. +<tscreen><verb> +$ mythtranscode --chanid 1036 --starttime 2003-10-20T15:30:00 --profile \ +autodetect --fifodir . & +</verb></tscreen> + +When <bf>mythtranscode</bf> begins executing, it will create two FIFOs +("audout" and "vidout") in the directory specified (in this case ".", +meaning the current directory) and will print out information about the +video stream. + +The next step is to start the processing application. The following assumes +that the stream is NTSC 640x480 with 32Kbps audio. + +To use <bf>mencoder</bf> you would enter a command like: +<tscreen><verb> +mencoder -audiofile audout -audio-demuxer 20 -rawaudio rate=32000 \ +-rawvideo on:w=640:h=480:fps=29.97 -ovc lavc -oac mp3lame -o out.avi \ +vidout +</verb></tscreen> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: You must use mencoder 1.0PRE1 or later. <bf>mencoder</bf> +version 0.9x <em>WILL NOT WORK!</em> +</caption> +</figure> +Using ffmepg: +<tscreen><verb> +ffmpeg -f u16le -ar 32000 -ac 2 -i audout -f rawvideo -s 640x480 -r 29.97 \ +-i vidout -vcodec mpeg4 -b 2000 -acodec mp3 -ab 128 out.avi +</verb></tscreen> + +Or to play directly using mplayer (again 1.0PRE1 or later is needed): +<tscreen><verb> +mplayer -audiofile audout -audio-demuxer 20 -rawaudio rate=32000 \ +-rawvideo on:w=640:h=480:fps=29.97 vidout +</verb></tscreen> + +If you wanted to write the raw data to separate audio and video files for +later processing, the following would work (note the use of --fifosync +for rate-control): +<tscreen><verb> +$ mythtranscode --chanid 1036 --starttime 2003-10-20T15:30:00 \ +--profile autodetect --fifodir . --fifosync & +$ cat audout > audio.raw & +$ cat vidout > video.yuv +</verb></tscreen> + +<sect1>Using a different window manager +<p>MythTV is not dependent on any particular window manager. If you wish to +run a lightweight window manager, the <tt>contrib/configfiles/</tt> directory has an +example of a <tt>.twmrc</tt> and <tt>.fvwmrc</tt> file you may use. + +<sect1>What capture resolution should I use? How does video work? +<label id="capture_resolution_"> +<!-- Lots of the following is from a Bruce Markey mailto:bjm@lvcm.com post +to the mailing list, 2003-01-21. Updated 2005-02-09 bjm --> +<p>While MythTV allows you to set various GUI and capture resolutions, not +all combinations make sense. + +First, analog video signals have a defined vertical resolution. In NTSC, +the video standard specifies that there are 525 vertical scan lines. Once +the "extra" lines are removed (they're used to synchronize the video signal, +and encode closed captioning data), you have 480 horizontal lines stacked +vertically. + +In PAL, there are 625 "raw" lines of resolution, with a net of 576 +horizontal lines stacked vertically. + +Horizontally, the maximum value allowed for a Bt8X8 chip is 720. However, +due to limitations in the chip and other limitations of broadcast +television, there may not be a noticeable improvement in image quality +beyond 400 or 500 pixels. + +With this in mind, there are certain commonly accepted values for +resolution. While other values may be accepted for the vertical +resolution, they will cause scan lines to be repeated or dropped. + +From "best" to "worst", in NTSC: +<itemize> +<item>720x480 "DVD" resolution. ReplayTV High and medium resolution +<item>704x480 DVD standalone recorder standard resolution +<item>640x480 4:3 +<item>544x480 TiVo Best resolution +<item>480x480 SuperVCD (SVCD) Video CD resolution, TiVo High resolution +<item>352x480 ReplayTV "Standard" quality, TiVo Basic and Medium resolution, DVD "LP" resolution +<item>320x480 +<item>544x240 +<item>480x240 +<item>352x240 Video CD (VCD) resolution +<item>320x240 +</itemize> + +As you can see, the lower quality values are half of the better ones. +720x240 is possible, but isn't a good tradeoff relative to the number of +vertical lines lost. In a PAL country, the you would use values like +720x576 or x288. + +The higher resolutions will be more CPU intensive if you're using software +encoding (PVR-250/350 will have minimal host CPU impact even if you're using +720x480). If the CPU is overtaxed, frames will be dropped causing uneven +motion. You will likely see the best results at resolutions which average at +least 10% CPU idle time. You can use system tools such as <tt>top</tt> or +<tt>sar</tt> to check the CPU % idle while recording. If the CPU average +usage is consistently exceeding 90%, frames will need to be dropped during +peak times when more than 100% of the available CPU would be needed to +process all of the frames. + +If you'd like to read more on this, go to the vcdhelp website at <url +url="http://www.vcdhelp.com/forum/userguides/94382.php" +name="http://www.vcdhelp.com/forum/userguides/94382.php">. + +<sect1>MythTV GUI and X Display Sizes +<p>MythTV is designed to be run as dedicated full screen TV application +but can also be run as a desktop application on a computer monitor. Here +are a few consideration for configuring sizes to best suit you needs. + +<sect2>X Dimensions +<p>For output to a Television, common resolutions are 640x480, 800x600, and +some rare devices support 1024x768. Generally, higher resolutions are +better. However, you may find that you prefer the picture quality at one of +the lower resolutions. Everything in MythTV is scalable and should 'fit' +regardless of the resolution you choose. + +Edit your X configuration file, usually <tt>/etc/X11/XF86Config-4</tt> for +XFree, or <tt>/etc/X11/xorg.conf</tt> for Xorg, so that the resolution you +want to use is listed first in the lists under "Screen". If this resolution +is higher than the resolutions supported by your output device, you will see +a 'panning' effect where moving the mouse to the edge will scroll around a +desktop area which is larger than the display size. If this happens, edit +your X configuration file to match the display size then restart X. + +<sect2>MythTV Dimensions +<p>From "mythfrontend" go to Setup->Appearance. +The default for the height and width is "0" - this will cause +MythTV to automatically size itself to full screen. + +If the MythTV GUI width and height are not 0, mythfrontend uses these GUI +dimensions and is anchored to the upper left corner of the X Desktop. If +the GUI X and/or Y are not 0, the upper left corner is positioned at the +specified coordinates. If the "Run the frontend in a window" box is checked, +the window will have a frame and can then be dragged to any position on the +desktop. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: When the GUI is full screen, you may see windows rapidly +flipping on top of each other. If this happens you will need to set your +window manager to 'Click to Focus' for windows to stack properly. +</caption> +</figure> +The fonts for the GUI and OSD will scale to whatever sizes you use. Most +font sizes can be changed in setup selections or in the .xml files under +<tt>/usr/local/share/mythtv/</tt> . Make sure to use fonts large enough +to be read on a TV screen from a distance. + +The full screen TV size is based on the X display size. For Xinerama, you +can specify a screen in Setup->General. The TV picture will be stretched +to fit the entire GUI area regardless of the <ref id="capture_resolution_" +name="capture resolutions"> used. However, during playback, the "W" key can +to used to correct differences between 16:9 and 4:3. + +<sect2>Overscan Dimensions +<p>Because picture edges can be ragged and screen edges aren't straight, +Television is designed to project an image larger than the physical screen. +This is called "overscan". Underscan is fitting the entire image inside the +screen. Underscan is useful for computer monitors so that toolbars and +scrollbars at the edges can be seen. + +For best results, match the X display area as close as possible to the edges +of the physical screen. This can only be adjusted by your tv-out device or +by the settings for the television set. Many sets have these adjustments in +a 'service mode'. If you cannot make these adjustments, there will be black +borders around the edges of the X desktop, MythTV GUI and TV playback. + +MythTV has settings for "Overscan" in Setup->Playback. These can not, and do +not, cause the image to display beyond the edge of the X display area. The +purpose of these settings are to cut off rough edges and to expand the image +so that objects will appear to be the same size as a normal overscanned TV +picture. + +<sect1>Saving or restoring the database <label id="backupdb"> +<p>See the <bf>mysqldump</bf> manpage for more information. +<tscreen><verb> +$ mysqldump -u mythtv -pmythtv mythconverg -c > mythtv_backup.sql +</verb></tscreen> + +To restore: (assuming that you've dropped the database) +<tscreen><verb> +$ mysql -u root +mysql>create database mythconverg; +mysql>exit +$ mysql -u mythtv -pmythtv mythconverg < mythtv_backup.sql +</verb></tscreen> + +You may need to alter the MySQL permissions if this database is being shared +with multiple systems. See the <ref id="modify_perm_mysql" name="Modifying +access to the MySQL database for multiple systems"> section for more +information. + +<sect1>Deleting the MySQL database +<p><figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Performing this step will remove the entire database. +You will lose all of your settings and will need to re-run the mc.sql script +to setup the database structure before running the mythtv-setup program. +</caption> +</figure> +<tscreen><verb> +$ mysql -u root +mysql> drop database mythconverg; +mysql> quit +</verb></tscreen> + +<sect1>Moving your data to new hardware +<p>This assumes that you will be moving your data to newer / bigger hardware +and don't want to lose your programs. + +The first step is to create a database backup as demonstrated in an earlier +section. + +Next, you will extract only the data that is relevant to the programs: +<tscreen><verb> +$ grep "INSERT INTO record " mythtv_backup.sql > restore.sql +$ grep "INSERT INTO recorded " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO oldrecorded " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO recordedprogram " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO recordedrating " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO recordedmarkup " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO recordedseek " mythtv_backup.sql >> restore.sql +</verb></tscreen> + +<bf>NOTE</bf>: Newer versions of <bf>mysqldump</bf> place backticks around +the table names. Backticks are not the same as apostrophes! On a typical +North American keyboard, backticks are located to the left of the "1" key, +on the same key as the tilde. Also, because the <bf>bash</bf> shell may try +to interpret the backticks, make sure you use a \ before each one. + +If your <tt>restore.sql</tt> file is empty, you'll need to re-run the +commands like this: +<tscreen><verb> +$ grep "INSERT INTO \`record\` " mythtv_backup.sql > restore.sql +$ grep "INSERT INTO \`recorded\` " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO \`oldrecorded\` " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO \`recordedprogram\` " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO \`recordedrating\` " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO \`recordedmarkup\` " mythtv_backup.sql >> restore.sql +$ grep "INSERT INTO \`recordedseek\` " mythtv_backup.sql >> restore.sql +</verb></tscreen> + +Note the space after the table name and the ">>" to append to the file for +all but the first <bf>grep</bf>. "recordedmarkup" and "recordedseek" are +huge and there may be hundreds of thousands of lines if you had lots of +hours of recordings. + +After you have moved the data files to the new hardware, configure MythTV +using the <bf>mythtv-setup</bf> program as you normally would with a +standard MythTV installation. + +At this point we will restore the information about your programs back into +the database: +<tscreen><verb> +$ mysql -u mythtv -pmythtv mythconverg < restore.sql +</verb></tscreen> + +After successful insertion of the data you may delete the +<tt>restore.sql</tt> file. + +<sect1>btaudio <label id="btaudio"> +<p>btaudio allows you to obtain the audio data from your tuner card directly +over the PCI bus without using a sound card. This is useful if you would +like to use multiple tuner cards in a system without adding a sound card for +each one, or if your existing sound card is not capable of full-duplex +operation. + +In order to use btaudio, your tuner card will need certain hardware +installed on it, and that hardware must be wired correctly. The chip that +will allow you to use the btaudio module is the MSP34xx. However, having a +MSP34xx is no guarantee that you will be able to use the btaudio module. + +As of 2003-03-31, this is the current list of cards and their status: +Works with btaudio: + +<itemize> +<item>Hauppauge WinTV-radio with dbx-TV stereo, model 401 +<item>Hauppauge WinTV-Theater, model 495, 498 (Europe) +<item>ATI TV Wonder +</itemize> + +The following cards do not work: +<itemize> +<item>Pinnacle Studio PCTV Pro - note: this has a MSP34xx, but it's not +wired correctly to the BT878 chip. +<item>ATI TV Wonder VE +<item>Leadtek Winfast 2000 XP (PAL, UK and NTSC) +<item>I/O Magic PC-PVR. No MSP34xx chip. +</itemize> + +The following cards have been reported to work, but have issues: +<itemize> +<item>Avermedia AVerTV Studio (no digital DSP output, "whiney noise" on +analog) +</itemize> + +Once btaudio loads, it should register additional <tt>/dev/dsp</tt> and +<tt>/dev/mixer</tt> devices. Typing <tt>$ dmesg</tt> will let you know +what's going on. + +<sect1>Removing unwanted channels +<p>If <bf>mythfilldatabase</bf> grabbed a channel which you do not want to +include in your TV listings, you can remove the entries from the grabber +configuration and the MySQL database. This often happens with premium +channels; for example, HBO or Showtime may be available on your cable TV +system, but is scrambled because you're not a subscriber to that channel. +Since you can never watch it, you want to get rid of it. + +If you are using the DataDirect service, login to your account at +<url url="http://labs.zap2it.com/" name="http://labs.zap2it.com/"> to +modify your lineup. Uncheck the boxes for any unwanted channels, and they +will no longer be included in your download. + +If you are using a grabber from XMLTV, comment out the channel from the +<tt>~/.mythtv/<sourcename>.xmltv</tt> file by inserting the word "not +" (including the space) in front of the unwanted entry. This will prevent +<bf>xmltv</bf> from grabbing future listings. + +Next, delete the unwanted item from the channel table so that it will not +appear in the EPG or when changing channels. To delete the data from the +database we need to perform some steps. First, assuming that HBO is channel +15, we need to find out the internal <tt>chanid</tt> used by MySQL: +<tscreen><verb> +$ mysql -u root mythconverg +mysql> select chanid from channel where channum=15; ++--------+ +| chanid | ++--------+ +| 1015 | ++--------+ +1 row in set (0.00 sec) +mysql> delete from channel where chanid = 1015; +</verb></tscreen> + +Old program data will be removed over the course of a week. However, you may +want to immediately delete any current program listings for the channel that +has been removed: +<tscreen><verb> +$ mysql -u root mythconverg +mysql> delete from program where chanid = 1015; +</verb></tscreen> + +<sect1>NFS +<p>You may want to use a central server to store your files. + +On the host machine, (in this case, the hostname is "masterbackend") you'll +want to edit your <tt>/etc/exports</tt> file and use something like: +<tscreen><verb> +/var/video (rw) +</verb></tscreen> + +To export the <tt>/var/video</tt> directory with read / write privileges. + +On the "slave" machine, you'll want to edit the <tt>/etc/fstab</tt> file and +add something like: +<tscreen><verb> +masterbackend:/var/video /var/video nfs rsize=8192,wsize=8192,hard,intr,nfsvers=3,actimeo=0 +</verb></tscreen> + +Then run <tt># mount -a</tt> to re-read the file to mount the file system. + +In this case, the source is a machine called "masterbackend" which is +exporting the directory "/var/video", which we're mounting locally at +"/var/video". The rsize and wsize options are used to increase the +performance of NFS; "hard,intr" is there because that's the recommendation +of the NFS-HOWTO, the nfsvers is required for filesizes over 2GB and actimeo +is used to turn off file attribute caching. Attribute caching for a shared +media point causes problems; you always want to see the latest state of the +directory and files. See <url +url="http://www.mythtv.org/wiki/index.php/Optimizing_Performance" +name="http://www.mythtv.org/wiki/index.php/Optimizing_Performance"> for +additional information regarding performance optimization. + +<sect1>Automatically starting mythfrontend at system boot time +<p>Here's an example submitted to the mythtv-dev list by Pat Pflaum +<url url="mailto:pat@netburp.com" name="mailto:pat@netburp.com"> using fvwm: +<tscreen><verb> +$ cat > .xinitrc +fvwm & +mythfrontend +^D +$ cat > .fvwmrc +Style myth* NoTitle, NoHandles, Sticky, WindowListSkip, SloppyFocus, GrabFocus, BorderWidth 0 +^D +$ +</verb></tscreen> + +The following also works with blackbox: +<tscreen><verb> +$ cat > .xinitrc +xset -dpms s off & +irxevent & +mythfrontend & +blackbox +</verb></tscreen> + +Make sure that your <tt>.blackboxrc</tt> file has: +<tscreen><verb> +session.screen0.focusNewWindows: True +session.screen0.focusModel: SloppyFocus +</verb></tscreen> in it. + +<label id="mythbackend_autostart"> +<sect1>Automatically starting mythbackend at system boot time +<sect2>Red Hat And Mandriva +<p>Here's a method for automatically starting mythbackend submitted by Mike +Thomson (<url url="mailto:linux@m-thomson.net" name="mailto:linux@m-thomson.net">) and Stu Tomlinson (<url +url="mailto:stu@nosnilmot.com" name="mailto:stu@nosnilmot.com">). + +Copy the files from the MythTV <tt>contrib</tt> directory or from Mike's web +site (<url url="http://m-thomson.net/mythtv/" +name="http://m-thomson.net/mythtv/">) as follows: + +<tt>etc.rc.d.init.mythbackend</tt> should be made executable and copied to +<tt>/etc/rc.d/init.d/</tt>: +<tscreen><verb> +$ cd contrib +$ su +# chmod a+x etc.rc.d.init.d.mythbackend +# cp etc.rc.d.init.d.mythbackend /etc/rc.d/init.d/mythbackend +</verb></tscreen> + +<tt>etc.sysconfig.mythbackend</tt> should be copied to +<tt>/etc/sysconfig/</tt>: +<tscreen><verb> +$ cd contrib +$ su +# cp etc.sysconfig.mythbackend /etc/sysconfig/mythbackend +</verb></tscreen> + +Edit <tt>/etc/sysconfig/mythbackend</tt> if you want to change the defaults +(the userid that should start mythbackend, location of the logfile and (if +required) the name and location of the mythbackend binary). + +Use <bf>chkconfig</bf> to make sure the script is called when +entering runlevels 3, 4 or 5: +<tscreen><verb> +$ su +# chkconfig --level 345 mythbackend on +# exit +$ +</verb></tscreen> + +<label id="logrotate"> +<sect3>Log files +<p>By default, the log file for mythbackend will be written to +<tt>/var/tmp/mythbackend.log</tt>. This has been tested and is known to work +on Mandriva and Red Hat, but many people prefer to place logs under +<tt>/var/log/</tt>. + +To do this, create a group called <tt>mythtv</tt> (or anything you prefer) +and add your usual MythTV users to that group. If you changed the user that +starts mythbackend from the default of root you <em>must</em> perform this +step. + +Create the directory <tt>/var/log/mythtv</tt> and set its +permissions as follows: +<tscreen><verb> +$ su +# mkdir /var/log/mythtv +# chown root:mythtv /var/log/mythtv +# chmod 0775 /var/log/mythtv +# exit +$ ls -ld /var/log/mythtv +drwxrwxr-x 2 root mythtv 4096 Apr 28 21:58 /var/log/mythtv/ +$ +</verb></tscreen> + +<!-- From an email by chris at cpr.homelinux.net on 2006-09-01 --> +Create a <tt>mythtv</tt> file in <tt>/etc/logrotate.d</tt>: +<tscreen><verb> +$ su +# cat > /etc/logrotate.d/mythtv +# Set default values for all log files first... + +# Rotate the logs once a week, or more frequently if they +# exceed 10Mb in size (size is checked daily). +weekly +size 10M + +# 'copytruncate' is used for logs generated by +# currently-running programs that should not be restarted +# (and can't be signalled to start a new log) after the +# rotation. It duplicates the existing log file and then +# sets the length of the existing file to 0. The only time +# this would break would be if the program writing the log +# was using lseek. +copytruncate + +# After rotating the files, leave the most recent rotated +# copy alone but gzip everything else to save space. +compress +delaycompress + +# If a log isn't present then don't worry about it. +missingok + +# Don't rotate an empty file. +notifempty + +# end of the global options + +/var/log/mythtv/mythbackend.log /var/log/mythtv/mythfrontend.log { + # Keep logs until they are 2 months old or the number of + # logs reaches 12. If the log files stay small, the age will + # kick in first and you'll only have 8 log files. If they + # get larger than 10Mb then you won't keep all 60 days. + rotate 12 + maxage 60 +} + +# Different options for mythfilldatabase: +/var/log/mythtv/mythfilldatabase.log { + rotate 2 +} +^D +# +</verb></tscreen> + +<sect3>Mandriva +<p>Mandriva adds one more twist in the form of the <tt>msec</tt> utility, +which runs regularly and (at the default or any higher security level) sets +permissions on many files, including those under <tt>/var/log</tt>. + +To tell msec about the MythTV log files and their directory, you need to +edit the <tt>/etc/security/msec/perm.local</tt> file to include the +following: +<tscreen><verb> +# /etc/security/msec/perm.local +# Local overrides to the msec program +# +# Full file path user.group permissions +/var/log/mythtv/ root.mythtv 775 +/var/log/mythtv/* root.mythtv 664 +</verb></tscreen> + +A copy of the above has been included in the contrib/ directory. You may +add it by typing: +<tscreen><verb> +$ cd contrib +$ su +# cat etc.security.msec.perm.local >> /etc/security/msec/perm.local +# exit +</verb></tscreen> + +Finally run the <tt>msec</tt> tool to check and implement your +changes. +<tscreen><verb> +$ su +# msec +# exit +$ +</verb></tscreen> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: msec can only <em>reduce</em> the permissions of files, so if +you don't get the results you expect, check that you're not asking +<tt>msec</tt> to add missing permissions to the files or directories you +created. +</caption> +</figure> +<sect2>Gentoo +<p>The portage file for MythTV has scripts that will allow you to run +mythbackend at startup. + +To run mythbackend as a daemon which starts at boot time: +<tscreen><verb> +# rc-update add mythbackend default +</verb></tscreen> +To stop mythbackend as a daemon: +<tscreen><verb> +# /etc/init.d/mythbackend stop +</verb></tscreen> + +To obtain a list of options: +<tscreen><verb> +# /etc/init.d/mythbackend +</verb></tscreen> + +<sect1>Advanced Backend Configurations <label id="advanced_backend_config"> +<p>MythTV is flexible in the way that you define multiple backend tuner +configurations. The only hard-and-fast rule is that the Master backend +<em>must</em> have a capture device defined, but shouldn't imply that the +capture device in the Master backend must be the first capture card defined in the +database. + +One example of an advanced configuration is the round-robin scheme. Rather +than defining all of the cards on the master, you could first go into +mythtv-setup on the master to define globals such as the general configuration +and the channel lineup but not the host-specific configuration item like the +capture card. In this example, we will use a 4 tuner configuration, where two +slaves have one card each and the master has two. +<enum> +<item>Add the first capture card on one of the slaves. Complete the +configuration, connecting the input source to the card. This will get +cardid #1 in the database. Exit mythtv-setup. +<item>Configure the first capture card on the master backend. This will get +cardid #2 in the database. Exit mythtv-setup. +<item>Configure the first capture card on the second slave. This will be +cardid #3 in the database. Exit mythtv-setup. +<item>Configure the second capture card on the master backend. This will +get cardid #4 in the database. Exit mythtv-setup. +</enum> + +Using this scheme, the master backend will not use both capture cards until +one of the following happens: +<itemize> +<item>There are four recordings scheduled for the same time +<item>Both slaves are unavailable +</itemize> + +The scheduler in MythTV checks whether an encoder is available; if a slave +backend isn't running, its encoder isn't available, so the scheduler will +look for the next available encoder. This makes MythTV very flexible; slave +tuners can come and go, and as long as there are enough tuners for what +you'd like to record it doesn't matter which tuner in particular is going to +be used. + +Using this round-robin scheme along with a shared storage directory like +NFS and enabling the Master Backend Override setting will allow you to view +content even if the slave backend that recorded a program is not available. + +<sect1>Using the transcoder +<!-- Aran Cox, spin667 at mchsi.com --> +<p>MythTV's built-in transcoder re-encodes recordings from one codec to +another. The transcoder has three primary uses; it can transcode MPEG-2 +files captured using a hardware encoder (PVR cards, DVB cards, ATSC HD, +etc.) to MPEG-4, it can be used to transcode RTjpeg files (usually only used +on systems that can not real-time encode to MPEG-4 using a framegrabber) to +MPEG-4, and finally it can be used to remove commercials from a MPEG-2 file +while leaving the file in MPEG-2 format. + +When MythTV transcodes a file to MPEG-4 or RTjpeg the resulting file format +is NuppelVideo (nuv). NuppelVideo is a container which provides a method of +keeping the audio and video in sync throughout the recording, which is why +it is used instead of the <tt>.avi</tt> format. You may have difficulty +playing <tt>.nuv</tt> files in non-MythTV systems. + +<!-- If +you want something more portable you can look at some of the other sections +in this HOWTO. --> + +The original file is removed when the transcoding process is complete. +Unless you're sure that you will be satisfied with the result you may want +to enable the <bf>mythtv-setup</bf> option which causes <bf>mythbackend</bf> +to keep the original file after transcoding. This option is on the second +page of the General section in mythtv-setup. Enabling this allows you to +compare the two files and restore the original if you like. Outside of the +initial setup phase it usually isn't necessary to leave this option enabled. +A recording can be transcoded in two ways: + +<itemize> +<item>Automatically transcode the file once it has completed +recording.</item> +<item>Manually choosing to transcode a recording, usually after +importing a cutlist or manually marking commercials to be +removed.</item> +</itemize> + +The second method can be used on files that have already been transcoded (or +files which were are already in the desired format), so only the frames +immediately following a cut section will be re-encoded, resulting in a +minimal loss of quality when removing commercials with the added benefit of +being extremely quick. + +The current transcoding system has a lot flexibility, but there are +a number of steps involved in setting it up. In order to +automatically transcode a given recording you must do the following: +<enum> +<item>Configure recording profile for your capture source and enable +transcoding on one or more profiles.</item> +<item>Configure one or more transcoding profiles.</item> +<item>Create or alter existing scheduled recordings to enable +transcoding for that recording.</item> +</enum> + +<sect2>Configuring Recording Profiles to Allow Transcoding + +<p>Enter the Utilities/Setup > Setup > TV Settings > Recording Profiles +section in <bf>mythfrontend</bf>. Choose the option that corresponds to +your capture source (ignore the Transcoders for now.) Choose the quality +profile you are interested in using for transcoding. Ensure that "Enable +auto-transcode after recording" is checked. <!-- This option might ought to +be called "allow auto-transcode" as we'll soon see though. You might want to +verify that the other settings for this profile are correct while your here. +--> + +<sect2>Configure Transcoding Profiles + +<p>Enter the Recording Profiles > Transcoders menu. There are three quality +settings to choose from and a two special Autodetect settings. Later, when +scheduling recordings you'll have to choose one of Autodetect, High, Medium, +and Low Quality transcode settings in addition to the recording profile we +set up above. If you choose the Autodetect transcoding profile for a +recording, MythTV will use the "Autodetect from RTjpeg/MPEG-4" profile for +recordings which are RTjpeg/MPEG-4 files. Otherwise, it will use the +"Autodetect from MPEG-2" profile provided it's an MPEG-2 recording. If you +choose one of the others (High, Medium, Low) it will use the settings in +that profile regardless of the codec of the original recording. + +There are a number of options for transcoding but the simplest is to enable +lossless transcoding (the first option) which subsequently removes all other +options. Enabling lossless encoding simply removes commercials (if you've +marked them) and attempts to clean up MPEG-2 streams. Note that with this +option MythTV will not apply any sort of filters and will only attempt to +normalize the stream into something cleaner and less likely to have trouble +with other less forgiving MPEG-2 hardware/software (including players, video +editors, etc.) + +If you enable resizing of the recording the next page has the settings for +choosing the final resolution. MythTV will scale the video as appropriate, +not crop it to this resolution. + +The final two pages allow configuration of the video and audio codecs. +Although RTjpeg is an option for video codec there is no reason to transcode +<em>to</em> this format because it will produce larger files than MPEG-4 and +the recording will take <em>more</em> CPU power to play back. The MPEG-4 +settings are described in the documentation for the <bf>ffmpeg</bf> project +at <url url="http://ffmpeg.sourceforge.net/ffmpeg-doc.html" +name="http://ffmpeg.sourceforge.net/ffmpeg-doc.html">. It's a matter of +trial and error to discover which settings achieve a good compromise between +size and quality. + +If you wish to return to the default settings, they are Bitrate: 2200-2500, +MaxQ: 2, MinQ: 15, MaxQDiff: 3, and "Scale bitrate for frame size" is +enabled. The other options are unchecked. <!-- If you're getting weird +results from MPEG-4 transcoding try setting as above and go from there. --> + +<sect2>Create/Alter Scheduled Recordings to Enable Transcoding + +<p>Transcoding is actually enabled on a per-recording basis. Two things +must be true before any given recording will be auto-transcoded, however. +The first is that the recording must have been made with a recording profile +that has auto-transcode enabled. Under "Storage Options" for the recording +you must set the "Record using the "X" profile" to the profile you +configured in the first step. In addition, under the "Post Recording +Options" section of the recording you must also set "Transcode new +recordings." This is also where you specify the Transcoding profile to use +(Auto, High, Medium, Low.) + +It may not be obvious from above but the flexibility of this system is +primarily to make it possible to auto-transcode a show recorded via one +source (ie: pcHDTV 3000), and not transcode that same show if it's recorded +on another kind of card (ie: PVR-250.) There are other uses however. You +could have a PVR-250 and a V4L card. You may want to transcode the MPEG-2 +from the PVR-250 but there is no need to transcode the recordings made with +the V4L card, as it's already likely to be MPEG-4. + +As an example, you could configure the Default profile for "Hardware DVB +Encoders" (the profile group used for DVB cards, including ATSC cards like +the pcHDTV 3000) to "Enable auto-transcoding". In the Default profile for +MPEG-2 Encoders (PVR cards) you'd leave "Enable auto-transcoding" unchecked. +For programs that are available on both kinds of cards you'd set the +recording profile to Default and enable auto-transcoding in the record +settings. Then you pick your transcoding profile. The result is that when +a program is recorded on your DVB card, it will get transcoded. When it +plays on a channel available via your PVR card, it won't be. + +<sect2>Manual Transcoding + +<p>Manually transcoding is activated while watching a show by hitting 'x', +from the OSD menu by choosing the Transcode option, or by choosing Job +Options/Transcode from the info menu from the Watch or Delete +Recordings screens. + +The transcoding profile used for manual transcoding is whatever was set when +the recording was originally configured, even if you didn't enable +auto-transcoding. The only way to change what transcoding profile will be +used is to alter the transcoder column in the recorded table in the +database. The transcoder column contains a number which corresponds with +the id column in the recordingprofiles table. You can find out the id +number for each profile in the transcoder group with an SQL command like: + +<tscreen><verb> +mysql> select r.* from recordingprofiles r,profilegroups p where p.name='Transcoders' and p.id=r.profilegroup; ++----+----------------+------------+------------+--------------+ +| id | name | videocodec | audiocodec | profilegroup | ++----+----------------+------------+------------+--------------+ +| 21 | RTjpeg/MPEG4 | MPEG-4 | MP3 | 6 | +| 22 | MPEG2 | MPEG-4 | MP3 | 6 | +| 27 | High Quality | MPEG-4 | MP3 | 6 | +| 28 | Medium Quality | MPEG-4 | MP3 | 6 | +| 29 | Low Quality | MPEG-4 | MP3 | 6 | ++----+----------------+------------+------------+--------------+ +5 rows in set (0.01 sec) + +mysql> +</verb></tscreen> + +Armed with the knowledge of what the profile ID's are you can also choose to +run mythtranscode from the command line and explicitly specify the transcoder +profile. Run <tt>mythtranscode --help</tt> for usage information. + +<sect1>Changing your hostname +<!-- Edited instructions from a post by Alan Snyder ax763 at yahoo.com --> +<p>If you need to change the name of the computers used with MythTV you'll +need to perform a sequence of steps. There are a number of pieces of +information that MythTV keeps track of which are tied to the hostname of the +box, so changing the hostname involves altering the name in the +operating system and in the MySQL database. In the examples below, the old +name of the system was "frontend1" and we're going to change it to +"kidsroom". + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: Changing the hostname using direct SQL update commands will +break things. You <em>MUST</em> use this indirect method. +</caption> +</figure> + +1. Stop all backends. If you run <bf>mythbackend</bf> from a terminal +session, press control-c. If your backends are started with an init +script, you would do something like the following: +<tscreen><verb> +$ su +# /etc/init.d/mythbackend stop +</verb></tscreen> + +2. Change the hostname. + +For Red Hat and derived distributions, edit the +<tt>/etc/sysconfig/network</tt> file. Look for +<tt>HOSTNAME=frontend1</tt> and change this to +<tt>HOSTNAME=kidsroom</tt> or whatever you'll be using. For other +distributions, refer to the documentation, such as the +<verb>hostname(1)</verb> man page. + +<p> +To alter the +hostname in the current session, run: +<tscreen><verb> +# hostname kidsroom +</verb></tscreen> + +3. Dump the database. +<tscreen><verb> +$ mysqldump -u mythtv -pmythtv mythconverg -c > mythtv_backup.sql +</verb></tscreen> + +4. Rename the host in the database. First, ensure that the new hostname +you'll be using isn't already in the database. +<tscreen><verb> +$ grep kidsroom mythtv_backup.sql +</verb></tscreen> +Now we're actually going to change the name. The following should all be +typed on the same line: +<tscreen><verb> +$ cat mythtv_backup.sql | sed s/\'frontend1\'/\'kidsroom\'/g >> mythtv_restore.sql +</verb></tscreen> +If you don't feel comfortable using <bf>sed</bf>, you can open the +<tt>mythtv_backup.sql</tt> file in a text editor and perform a global search +and replace. When saving the file, make sure you use the new name, +<tt>mythtv_restore.sql</tt> or the rest of the steps below will fail. + +5. Drop and recreate the database. +<tscreen><verb> +$ mysql -u root +mysql>drop database mythconverg; +mysql>create database mythconverg; +mysql>exit +</verb></tscreen> + +6. Restore the database using your edited version. +<tscreen><verb> +$ mysql -u mythtv -pmythtv mythconverg < mythtv_restore.sql +</verb></tscreen> + +If you are running slave backends or frontends, don't forget to re-enable +access as detailed in <ref id="modify_perm_mysql" name="Modifying access to +the MySQL database for multiple systems">. + +7. Start the backends. If you use init scripts, do the following, otherwise +start them from terminal consoles. +<tscreen><verb> +# /etc/init.d/mythbackend start +</verb></tscreen> + +8. Quit and restart all frontends. Delete the <tt>mythtv_backup.sql</tt> +and <tt>mythtv_restore.sql</tt> files. + +<sect1>Can I run MythTV on my TiVo? +<sect1>Can I run MythTV on my ReplayTV? +<p>No. + +While it is true that the TiVo runs the Linux kernel, and TiVo has released +their changes to the kernel under the GPL, the TiVo is <em>not</em> a +general-purpose computer, and there is no programming information available +for the custom hardware contained within a TiVo. TiVo is under no +obligation to release the source code to their <em>application</em>. + +The ReplayTV runs VxWorks, a Real Time Operating System from Wind River +Systems. +<sect1>Can a wireless connection be used between the frontend and the backend? +<p>Yes, assuming that your wireless connection has sufficient bandwidth to +maintain the datarate between the frontend and the backend. 802.11b should +be sufficient if the encoded bitrate of the content is less than the +datarate of your wireless connection, which in the case of 802.11b would be +approximately 4 Mbps. (The advertised rate of 11Mbps gives an actual +throughput of 4 Mbps.) 802.11a and 802.11g, if operating in their high-speed +modes, or proprietary 802.11b "Turbo" schemes should be adequate. Multiple +wireless frontends, poor signal strength or other factors can severely +impact the viewing experience on the frontend. + +<sect1>How can I burn shows that I have recorded to a DVD? +<p>Use the mytharchive plugin. + +<sect1>Using the DBoxII within MythTV +<p>The configuration of the DBoxII for use within MythTV is tricky (as of +May 16 2005), that's why it's covered here. Your DBoxII has to be running +linux and the Neutrino GUI instead of the stock BetaNova firmware. For +further information, please refer to <url url="http://www.tuxbox.org" +name="http://www.tuxbox.org">. Additionally, you need to enable the SPTS +mode in Neutrino. + +<itemize> +<item>Add a new "Capture Card" in the setup. The "Card type" is "DBOX2 Input", +the other values have to be adjusted according to your setup. +The default values, except for the "DBOX2 host ip", should work fine. +<item>Define a new video source. It doesn't need to be configured, +you just need to define it. MythTV grabs the EPG from the DBoxII. +<item>Connect the DBoxII to the newly defined input source in "input connections". +<item>Since channel scanning is not implemented yet, you need to define channels +in the "Channel Editor". Make sure that you use the same value for +"Channel Name" as on the DBoxII. You can get a list of available +channels from the web interface of Neutrino at http://ip-of-your-box:80/. +Associate the channel with your new video source and repeat when needed. +</itemize> + +You may leave the Setup now and proceed as usual. + +<sect1>What do the icons on the Watch Recordings screen mean? +<p>Press "1" or F1 to get a popup. +<sect1>What do the letters mean when I change channels? +<p>These letters let you know what's going on with the backend as it tries +to tune to a channel. + +Lower case = seen + +Upper Case = seen & good +<itemize> +<item>l/L = Lock : This could be seen by PVR-250/BTTV users +<item>a/A = PAT : Any recording transmitted in MPEG +<item>m/M = PMT : Any recording transmitted in MPEG +<item>g/G = MGT : ATSC only +<item>v/V = VCT : ATSC only +<item>n/N = NIT : DVB only +<item>s/S = SDT : DVB only +</itemize> +<sect1>What is the difference between the various Hauppauge PVR models? +<p>This is covered in the hardware section, and extensively covered on the +Hauppauge website. (<url +url="http://www.hauppauge.com/pages/compare_pvr.html" +name="http://www.hauppauge.com/pages/compare_pvr.html">) Please check the +Hauppauge website for the most accurate information. + +A PVR-150 comes in a number of versions: +<itemize> +<item>The PVR-150 (Model 1045) is the retail kit. It comes with a remote +control and an IR Blaster. It does not have a radio tuner. +<item>The PVR-150 MCE (Model 1042) will usually come in a plain white box and is +sold as an OEM device. It does not come with a remote control, since it's +usually used as the second, third, etc capture device. +<item>The PVR-150 MCE Kit (Model 1062) does not have a radio tuner and +comes with a Microsoft Media Center remote control instead of Hauppauge's. +<item>The PVR-150 low profile (Model 1086) is a low-profile card. It has a +radio tuner and is approximately half the height of a standard card. +However, it comes with a low-profile PCI bracket, so it is not suitable for +use in a standard PCI slot without removing the bracket, which may not be +worth the trouble. +</itemize> + +A PVR-250 (Model 980) is a retail kit which comes with an IR receiver and a +remote control. + +The PVR-250 MCE (Model 975) contains a FM radio tuner. The PVR-250 MCE does +not contain a IR receiver or a remote. + +The PVR-250 Rev 1 contained an MPEG-2 decoder. However, this function was +not connected to any output jacks, and there doesn't appear to be any way to +pull decoded video from the card, so it's a fairly useless feature. + +The PVR-350 (model 990) has the features of the PVR-250 as well as being +able to decode MPEG-2. The encode and decode functions may be used +simultaneously. The MPEG-2 decoder function gives superior video quality +compared to what you'll find on a standard video card. However, the decoder +function is only available once Linux has started, so you will not see any +boot-time messages. Also, the card is not capable of resolutions higher +than 720x480, so it cannot be used with HDTV. Make a conscious decision +(and ask for advice on the mailing list) that you want to tradeoff potential +HDTV use in the future compared to video quality. + +The X-driver for the PVR-350 support playback using Xv efficiently but does +not support any other 2D or 3D acceleration. For some application this may +place a large load on the host CPU, some will run without any problem and +others (mplayer, xine, xmame etc.) should be configured to utilize the Xv +interface. + +Note that for the PVR-350 there are some <ref id="PVR-350" name="considerations"> +regarding the way audio is handled. + +The PVR-500 is a dual-encoder version of the PVR-150 card, so you can +simultaneously record two different programs at the same time, because there +are two encoder chips on the PCI card. Hauppuage has also installed an +onboard splitter, so you can use one COAX to feed both tuners. Current +versions of the PVR-500 should come with an adapter to allow you to connect +a second S-Video or composite input, but this will take up a second PCI +slot. Early adopters may need to purchase this item separately. + +<sect1>Changing channels on an external Set Top Box +<p>If you need to use an external Set Top Box (STB), such as for satellite +TV or for digital cable you will need some way for MythTV to tell the STB to +switch to a new channel. There are several methods: +<enum> +<item>Use an IR blaster. An IR blaster is an infrared transmitter connected +to your computer. When MythTV needs to change channels it will send IR +pulses, thereby emulating a remote control. +<item>Use a direct serial connection. Some STB's have a serial port on the +back, although it may not look like a serial port. It may look like a phone +jack, or a strange VGA connector. It may be labeled "Low Speed Data". A +direct serial connection is more reliable than an IR blaster. Not all STB's +that have a Low Speed Data port have it enabled; you may need to convince +your service provider to turn it on. Stating that you have a Tivo may help; +the Tivo has a direct-connect capability. +<item>Use a firewire connection. There is a <tt>6200ch.c</tt> in the MythTV +contrib directory which may work for you. +</enum> +<sect1>Configuring one machine to flag all commercials +<p>Commercial flagging can be CPU intensive. By default, the backend that +created a recording is the one which will flag commercials. You may wish to +use a different machine to run commercial flagging. + +On the slower machine: + +Start the mythtv-setup program. Advance through the pages until you get to +the Job Queue page. Turn off the setting that says "Allow Commercial +Detection jobs", thereby preventing any commercial flagging jobs from +running on this machine. + +Next, make sure that "Run Jobs only on original recording host" is turned +OFF so that new jobs are allowed to run anywhere. + +Restart <bf>mythbackend</bf> since it only reads this setting when it starts +up. + +On the faster machine: + +Start the <bf>mythtv-setup</bf> program. Advance through the pages until +you get to the Job Queue page. Ensure that "Allow Commercial Detection +jobs" is turned ON for this machine. + +Run <bf>mythjobqueue</bf>. <bf>mythjobqueue</bf> will examine the JobQueue +and run any jobs it finds. <bf>mythjobqueue</bf> should be left running so +that it will pick up any new commercial flagging jobs that are added to the +queue, otherwise new jobs will be added to the queue and your programs won't +be flagged until you run manually run <bf>mythjobqueue</bf>. + +Using this technique it's possible to add commercial flagging machines as +needed, even on systems that aren't running a backend. It's also possible +to run the commercial flagger in a virtual machine environment such as +VMWare. + +<sect>Example Configurations. +<sect1>Logical Volume Manager (LVM) <label id="LVM"> +<!-- Contributed by Martin Smith martin at spamcop.net --> +<!-- XXXXX REMOVE ME FOR 0.22 --> +<p>LVM greatly increases the flexibility you have in managing your storage +than traditional physical partitions. This section will provide some brief +notes on how to use LVM to create storage space for your video files and how +to add additional disk space in the future. There's lots more that can be +done with LVM, so check the LVM HOWTO <url +url="http://tldp.org/HOWTO/LVM-HOWTO/" +name="http://tldp.org/HOWTO/LVM-HOWTO/"> document for details. + +<p><figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +<bf>NOTE</bf>: If you are running MythTV 0.21 and you are using LVM to +create one large filesystem to store your recordings, it's no longer +recommended that you go the LVM route. The preferred solution is to use <ref +id="storagegroups" name="Storage Groups">. They're more flexible and less +likely to lose all of your recordings if you have a drive failure. +</caption> +</figure> + +If you don't understand how to partition a drive, or how to change the +partition type you should stop and look at documentation on how to perform +these steps. + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption> +<bf>BIG FAT WARNING</bf>: Using an incorrect parameter can make your files +inaccessible, prevent your computer from booting, etc. Be careful! +</caption> +</figure> + +Make sure your kernel configuration includes LVM support or that it's +available as a module. Today, most vendors include this by default. You'll +also want to ensure that you have a copy of the LVM utilities; check your +distribution, or get the latest versions from <url +url="http://www.sistina.com/products_lvm.htm" +name="http://www.sistina.com/products_lvm.htm"> and build them manually. + +Check that the <bf>vgscan</bf> program is being run at some point during +your boot sequence - most distributions do this by default. Look for a +message during boot up that looks like this: <tt>vgscan -- reading all +physical volumes (this may take a while...)</tt> If you don't see any +messages during boot, you may need to install a LVM init script or confirm +that you have all of the LVM packages installed from your distribution. + +LVM uses a few concepts you should be familiar with before starting. +<itemize> +<item>PV (Physical Volume). The actual partition on the hard drive. +<item>VG (Volume Group). The aggregation of all the PVs make a VG. +<item>LV (Logical Volume). Subdivision of the pool of space available in +the VG into individual chunks, like /usr, /var/video, etc. +</itemize> + +The following example assumes that you want to create a LVM partition from a +chunk of space in /dev/hda5, using a reiserfs filesystem and mounted on +/var/video. You later decide to extend this filesystem by adding a new disk: +/dev/hdb. + +You need to create at least one LVM partition for a physical volume. Use +<bf>fdisk</bf> or your favorite partition editor to set the type to LVM +(0x8e). If you're using an entire disk, create one big partition rather than +using the device itself. e.g. use /dev/hdb1 not /dev/hdb. + +In the following example, you have a 15GB disk. The first 6GB are set as +your boot partition. <tt>/dev/hda2</tt> was added as an extended partition, +and within that partition you created the <tt>/dev/hda5</tt> linux (ext2) +partition. + +<tscreen><verb> +# fdisk /dev/hda + +The number of cylinders for this disk is set to 1823. +There is nothing wrong with that, but this is larger than 1024, +and could in certain setups cause problems with: +1) software that runs at boot time (e.g., old versions of LILO) +2) booting and partitioning software from other OSs + (e.g., DOS FDISK, OS/2 FDISK) + +Command (m for help): p + +Disk /dev/hda: 15.0 GB, 15000330240 bytes +255 heads, 63 sectors/track, 1823 cylinders +Units = cylinders of 16065 * 512 = 8225280 bytes + + Device Boot Start End Blocks Id System +/dev/hda1 * 1 764 6136798+ 83 Linux +/dev/hda2 765 1823 8506417+ 5 Extended +/dev/hda5 765 1823 8506417 83 Linux + +Command (m for help): t +Partition number (1-6): 5 +Hex code (type L to list codes): 8e + +Command (m for help): p + +Disk /dev/hda: 15.0 GB, 15000330240 bytes +255 heads, 63 sectors/track, 1823 cylinders +Units = cylinders of 16065 * 512 = 8225280 bytes + + Device Boot Start End Blocks Id System +/dev/hda1 * 1 764 6136798+ 83 Linux +/dev/hda2 765 1823 8506417+ 5 Extended +/dev/hda5 765 1823 8506417 8e Linux LVM + +Command (m for help): w + +# +</verb></tscreen> + +Create the LVM physical volume from the partitions (repeat if you have +multiple partitions to use): +<tscreen><verb> +# pvcreate /dev/hda5 +</verb></tscreen> +Create a LVM volume group out of this physical volume called "VGforMyth" that is +allocated in chunks that are a multiple of 64MB +<tscreen><verb> +# vgcreate VGforMyth -s 64m /dev/hda5 +</verb></tscreen> +Create a logical volume of 5GB called "video" and then create the reiserfs +filesystem and mount it: +<tscreen><verb> +# lvcreate --name video --size 5G VGforMyth +# mkreiserfs /dev/VGforMyth/video +# mount /dev/VGforMyth/video /var/video +</verb></tscreen> +Now create a 3GB volume for mythmusic files if you like: +<tscreen><verb> +# lvcreate --name music --size 3G VGforMyth +# mkreiserfs /dev/VGforMyth/music +# mount /dev/VGforMyth/music /var/music +</verb></tscreen> +Display the volume group status: +<tt># vgdisplay -v</tt> + +Now, lets suppose you want to add a 60GB hard disk to the system as hdb and +allocate 50GB of it to video storage. + +First, create a single partition /dev/hdb1 covering the whole disk and make +it type 0x8e using your partition editor. + +<tt># fdisk /dev/hdb</tt> +.... create partition, set type, save and reboot if it says you have to + +Create the new LVM physical volume: + +<tt># pvcreate /dev/hdb1</tt> + +Add the new physical volume to the volume group: + +<tt># vgextend VGforMyth /dev/hdb1</tt> + +<figure loc="here"> +<eps file="stop.eps" height="1cm"> +<img src="stop.png"> +<caption><bf>NOTE</bf>: You may get errors at this point stating that there are no +physical volumes available for adding to the LV, even though you know for a +fact that there are. You may need to specify the physical volume in the +<tt>/dev/ide/host/bus/target/lun/etc</tt> format. +</caption> +</figure> +Once you've completed one of the following two procedures, use <bf>df</bf> +to check that you've got more space. + +Make the logical volume used for video bigger: + +<tt># lvextend --size +50G /dev/VGforMyth/video</tt> +<sect2>ReiserFS +<p>Unmount, resize and remount the filesystem. Technically, you don't need to +unmount and remount the ReiserFS. +<tscreen><verb> +# umount /var/video +# resize_reiserfs /dev/VGforMyth/video +# mount /dev/VGforMyth/video /var/video +</verb></tscreen> + +<sect2>ext2 or ext3 +<p>LVM comes with a program called <bf>resize2fs</bf>. + +Unmount, resize and remount the filesystem. The filesystem <em>must</em> be +unmounted during this procedure. +<tscreen><verb> +# umount /var/video +# resize2fs --size +50G /dev/VGforMyth/video +# mount /dev/VGforMyth/video /var/video +</verb></tscreen> +<sect2>xfs +<p>XFS does not need to be unmounted to extend the size: +<tscreen><verb> +# xfs_growfs /var/video +</verb></tscreen> +<sect1>Advanced Partition Formatting <label +id="advancedpartitionformatting"> +<p>The partitions that your distribution sets up for you may not be +optimized for large files. Using LVM in conjunction with the following +techniques can be quite useful. + +Unlike a typical filesystem, a MythTV video partition is usually a very +large filesystem filled with a fairly small number of large files. +Filesystem I/O is usually not an issue, even in multi-tuner and/or +multi-frontend setups. + +There is however, one aspect of filesystem performance that can have a +bearing on the performance of MythTV. In Linux, deleting a file will +utilize I/O bandwidth until the deletion has been completed. If deleting +the file takes long enough, the video capture buffer may overrun, thereby +resulting in dropped frames. Some filesystems are faster at deleting files +than others and, for multi-gigabyte MythTV video files, these differences +can be significant. + +Fortunately, there are published tests (<url +url="http://aurora.zemris.fer.hr/filesystems/big.html" +name="http://aurora.zemris.fer.hr/filesystems/big.html">) that provide +insight into filesystem performance under conditions relevant to MythTV +usage. In addition, some limited testing (archived at <url +url="http://www.gossamer-threads.com/lists/mythtv/users/52672" +name="http://www.gossamer-threads.com/lists/mythtv/users/52672">) +with very large files (10 gigabytes) was reported in the MythTV Users +mailing list. + +<sect2>Ext2 +<p>Ext2 was the defacto standard Linux filesystem for many years. It is +stable, provides good I/O performance and can quickly delete large files. +The primary disadvantage of Ext2 is that it is not a journaling filesystem, +so a file system consistency check (fsck, which is normally only performed +after a system crash) can take many hours on a filesystem the size of a +typical MythTV partition. + +<sect2>Ext3 +<p>Ext3 is Ext2 with a journal, so your biggest gain is that in case of a +crash and reboot you won't have to wait very long for your partition to be +remounted. + +There are options available when formatting an Ext3 partition, as in: +<tscreen><verb> +# mkfs.ext3 -T largefile4 /dev/hdb1 +</verb></tscreen> + +This example assumes that <tt>/dev/hdb1</tt> has already been created using +<bf>fdisk</bf>. If you're using LVM, <tt>/dev/hdb1</tt> may be something like +<tt>/dev/VGforMyth/video</tt>. + +The "-T largefile4" option creates one inode per 4 megabytes, which can +provide a few percent more storage space. However, tests indicate that +using the "-T largefile4" option can drastically increase the amount of time +required to delete a large file and thus it should only be used with encoder +settings that produce small video files (YMMV). + +You can check on your filesystem using the <bf>dumpe2fs</bf> program. See +the man page for details. +<sect2>ReiserFS +<p>The Reiser filesystem is another journaling filesystem commonly +distributed with Linux. It is known to be an extremely efficient filesystem +and it especially excels at managing partitions containing a large number of +small files. However, tests indicate it is not the fastest at deleting very +large files. For that reason, it may not be the best choice when using +encoder bitrates that produce very large files. + +<sect2>JFS +<p>JFS (Journaling File System) is a journaling filesystem originally +developed by IBM for AIX which was later released as open source. While not +as common as Ext3 or ReiserFS, it is distributed with RedHat 9 (RH9), Fedora +Core and Mandriva as well as other distros. According to tests, JFS is the +file deletion speed king, deleting virtually any file in under one second, +even files as large as 10 gigabytes. + +<sect2>XFS +<p>XFS is a journaling file system originally developed by SGI for Irix, and +later released as open source. While not a part of the default RedHat Linux +9 or Fedora Core installation (although it is a part of Mandriva and Fedora +Core 2+), it can be easily installed via ATrpms. XFS provides deletion +speeds for large files only slightly slower than JFS. According to the test +results shown at (<url +url="http://aurora.zemris.fer.hr/filesystems/big.html" +name="http://aurora.zemris.fer.hr/filesystems/big.html">), XFS provide +higher I/O rates than JFS, albeit at a higher CPU loading. This may cause +issues if you do not have the spare CPU capacity to handle XFS, potentially +leading to dropped frames. + +<label id="migratingtoSD"> +<!-- Mostly from a post by Bruce Markey --> +<sect1>Migrating from DataDirect Labs to Schedules Direct + +<p>MythTV v0.20.2 or later is required to natively support Schedules Direct. +Code has been included to make the transition as simple as possible. + +<bf>You do not need to delete your existing video sources or add new ones!</bf> + +The following steps should work for most users: +<itemize> +<item>Create a Schedules Direct account and use the same information as your +existing lineups at Zap2It Labs. Do not add or delete channels at this +time. +<item>Shut down any running <bf>mythfrontend</bf> and <bf>mythbackend</bf> programs. +<item>Perform a backup of your existing database. See <ref id="backupdb" +name="Saving or restoring the database"> for instructions. +<item>Run <bf>mythtv-setup</bf> -> Video Sources. Change the grabber to +Schedules Direct, update the username and password fields with the account +information you created at Schedules Direct and select "Retrieve Lineups". +Click Finish. +<item>Exit <bf>mythtv-setup</bf> and run <bf>mythfilldatabase</bf>. Check +if there were any errors. +<item>Restart your <bf>mythbackend</bf> and <bf>mythfrontend</bf> programs. +</itemize> + +<sect1>Caching support for Schedules Direct +<p>MythTV 0.20.2 or later supports caching of downloaded information from +Schedules Direct, so devices that share a common source do not require +multiple downloads. + +Before beginning, perform a backup of your existing database. See <ref +id="backupdb" name="Saving or restoring the database"> for instructions. + +In the following scenario, assume that you have the following: +<enum> +<item>A PVR-150 MPEG-2 encoder card connected directly to a CATV source. +<item>A PVR-250 MPEG-2 encoder card connected via S-Video to a CATV Set Top Box. +</enum> + +What we are going to do is to create a single lineup at Schedules Direct and +then create two Video Sources which use the same login information but have +different channels associated with them. + +On your Schedules Direct account, create a lineup that has all of the +channels that you can receive. Because we have a Set Top Box (STB), choose +a Digital lineup. Yes, this means that you may have 900 channels in this +lineup, but that's OK. + +Use the Schedules Direct channel editor and unselect any channels that you +can't tune without the STB. This will usually be channels higher than 125, +but check your CATV provider lineup if you're not sure. Once you've +deselected them (using a click on the first channel you can't receive and +then a shift-click on the last channel you can't receive will deselect all +the channels in between those two.) click the Save Changes button at the +bottom of the screen. + +In <bf>mythtv-setup</bf>, create a Video Source with an appropriate name. +"SD-Analog Only" will be used in this example. Click "Retrieve Lineups" +and select the digital lineup you just created at Schedules Direct. + +Click "Finish" to return to the Video sources selector and then press the +ESC key to go back to the main screen. + +Now choose Input Connections. Select the PVR-150 which is connected +directly to the CATV. Set the Video Source to "SD-Analog Only" and click +"Fetch channels from listings source". + +Set the start channel to an appropriate value. + +<bf>NOTE</bf>: There is a bug where the "Fetch" command may not work; you +can tell that the Fetch did not retrieve any channels in one of two ways: in +the text-mode console, you will see a connection to Schedules Direct, but it +doesn't appear to retrieve any channel information: +<tscreen><verb> +2007-08-25 15:03:05.526 New DB DataDirect connection +2007-08-25 15:03:05.526 Connected to database 'mythconverg' at host: localhost +2007-08-25 15:03:05.536 DataDirect: Your subscription expires on 11/23/2007 01:12:10 PM +2007-08-25 15:03:05.707 New DB connection, total: 3 +2007-08-25 15:03:05.707 Connected to database 'mythconverg' at host: localhost +2007-08-25 15:03:05.708 sourceid 2 has lineup type: CableDigital +2007-08-25 15:03:06.623 Data fetching complete. +2007-08-25 15:03:06.624 DataDirect: Deleting temporary files +</verb></tscreen> + +or, the "Please add channels to this source" message in the "Starting +channel" field stays on the screen. + +If either of these happens, save the information on this screen by clicking +the "Finish" button. Exit back to the Input connections screen by pressing +ESC, then select this Input Connection again. This time the Fetch will work +and the "Please add channels to this source" message will disappear. + +If you look at the text-mode console, you'll see this if the channel +retrieval is working: +<tscreen><verb> +2007-08-25 15:04:32.437 New DB DataDirect connection +2007-08-25 15:04:32.437 Connected to database 'mythconverg' at host: localhost +2007-08-25 15:04:32.447 DataDirect: Your subscription expires on 11/23/2007 01:12:10 PM +2007-08-25 15:04:32.622 New DB connection, total: 3 +2007-08-25 15:04:32.622 Connected to database 'mythconverg' at host: localhost +2007-08-25 15:04:32.623 sourceid 2 has lineup type: CableDigital +2007-08-25 15:04:33.418 DataDirect: Adding channel 41 'AMC' (AMC). +2007-08-25 15:04:33.422 DataDirect: Adding channel 32 'A & E Network' (AETV). +2007-08-25 15:04:33.425 DataDirect: Adding channel 66 'Black Entertainment Television' (BET). +2007-08-25 15:04:33.427 DataDirect: Adding channel 180 'Bravo' (BRAVO). +2007-08-25 15:04:33.430 DataDirect: Adding channel 51 'ABC Family' (FAM). +2007-08-25 15:04:33.432 DataDirect: Adding channel 146 'Country Music Television' (CMTV). +2007-08-25 15:04:33.435 DataDirect: Adding channel 39 'CNBC' (CNBC). +2007-08-25 15:04:33.437 DataDirect: Adding channel 36 'Cable News Network' (CNN). +2007-08-25 15:04:33.440 DataDirect: Adding channel 35 'CNN Headline News' (CNNH). +</verb></tscreen> + +Repeat the Input Connection configuration for any other capture devices that +are connected directly to the CATV system. You do not need to click Fetch +once you've done one successful download of the channel information - the +Starting channel should be automatically populated. + +Go back to Schedules Direct and re-enable the channels that you had +previously deselected, then click Save Changes. + +Create a new Video Source, here called "SD-All Digital Channels". Perform +the same "Retrieve Listings" you did before. + +Go back to the Input Connections screen, select the PVR-250 which is +connected to the STB, assign the "SD-All Digital Channels" video source and +perform a retrieve channels. This will pull down the complete channel +listing, but only for <em>this</em> device. + +When <bf>mythfilldatabase</bf> runs, it will cache the "big" download which +is appropriate for the STB, and then copy the information to the channels +that can only be accessed without the STB. But by default +<bf>mythfilldatabase</bf> is going to notice that the "Analog only" video +source is missing the channels that are in the Digital lineup you created at +Schedules Direct, so we need to override the addition of new channels. + +When you run <bf>mythfilldatabase</bf> to populate your database, you'll +need to run it like this: + +<tscreen><verb> +$ mythfilldatabase --remove-new-channels +</verb></tscreen> + +You will also need to modify how the <bf>mythbackend</bf> calls +<bf>mythfilldatabase</bf> when it performs its automatic listings update. + +In <bf>mythfrontend</bf>, select "Setup" -> "General". + +Continue press ENTER until you reach the Mythfilldatabase configuration +screen. In the "mythfilldatabase Arguments" field, type +--remove-new-channels + +then press the TAB key until you reach Finish, then press ENTER to save. +You can then press ESC until you return to the main screen. +</article> +<!-- Revision History + +v0.21.00, 2008-03-10. Initial version for 0.21. Update link to ATSC +devices. Add note that ivtv driver is in kernel. Add note that xbox +mini-distribution site appears dead. Update information on HVR-1600. +Update minimum MySQL version. +v0.21.01, 2008-06-03. Add mythbuntu. +v0.21.02, 2008-06-04. Update minimyth link. +--> + +<!-- +To create documentation, run "make" in the docs/ subdirectory +--> + +<!-- Basic Style Guide for the HOWTO. + +Paths are specified with <tt> + +Program names are specified with <bf> + +Use full close tags, such as </tt> rather than the "/>" shortcut. + +For a URL link, the url= and name= should be the same. This ensures that +users who are reading the text version of the document will see what the URL +is. + +For "Notes", the format is <bf>NOTE</bf>: text here. + +label id's must be contained on one line. If they break across the right +margin the wrapped text will be considered as text and not a destination. + +Don't make a section "a" if there's no section "b". Same for numbers; no +number 1 if there's no number 2, etc. + +Itemized and enumerated items should be full sentences, and should end with +a period. + +All major sections end with a period; subsections don't. + +Dates must be in ISO8601 format YYYY-MM-DD. + +--> |