Linux Beach MultiMedia Center

Users Guide

Table Of Contents

1. What is MythTV?
2. History
3. Features
4. Quick Start Guide
5. Remote Commands
6. Keyboard Commands
7. Administrative Information
8. Scheduling Recordings.
9. Record Types
10. Scheduling Options
11. Storage Options
12. Post Recording Processing
13. Advanced Recording Options
14. Watching a DVD or VCD
15. Ripping a DVD
16. MythVideo
17. MythMusic
18. MythGallery
19. MythWeather
20. MythPhone
21. MythNews
22. MythBrower  
23. MythGame
24. MythArchive
25. MythFlix
26. MythWeb
27. Advanced Setup Topics
28. LBMC Blaster codesets
29. Nvidia Setup

What is MythTV?

MythTV is shell that organizes a tremdous amount of open source multimedia software for the purpose running your home entertainment system.
MythTV is a collection of software which runs under the Linux operating system, and provides the functions commonly known as a PVR or DVR (personal, or digital, video recorder) — essentially, it's a computerized VCR, similar to a TiVo or a Replay... but since it's open source software, if you don't like the way it does something, you can always change it — that's how much of its current functionality came about in the first place.

In addition to the basic PVR functions of recording and playing back scheduled programs and allowing you to schedule recordings automatically in advance, MythTV has a plugin system which permits it to be extended by other programmers; plugins currently exist for playing external video, viewing photos and listening to music files, using your TV and a web camera as a video-telephone over the Internet, browsing the web, retrieving current local weather, and many other functions.

History

He says:

I got tired of the rather low quality cable box that AT&T Broadband provides with their digital cable service. It's slow to change channels, ridden with ads, and the program guide is a joke. So, I figured it'd be fun to try and build a replacement. Yes, I could have just bought a TiVo, but I wanted to have more than just a PVR -- I want a webbrowser built in, a mail client, maybe some games. Basically, I want the mythical convergence box that's been talked about for a few years now.

So, in late April 2002, I started tinkering with stuff. I bought a cheap TV tuner card from Best Buy, and threw it into my desktop box (P3-550). I started playing around with different video encoders, and eventually decided that NuppelVideo provided the best quality video for the amount of CPU it took up. It's based on a modified RTjpeg codec, and it looks rather nice, in my opinion.

Unfortunately, the poor P3-550 really couldn't encode and decode video at the same time. So, I took the plunge and bought a better machine — an Athlon XP 1800+. I based the machine off of an Abit NV7-133R motherboard, and put it into a nice black case.

See the news updates/archives for what's happened since.

Features

MythTV provides home theatre functions such as the ability to:

• PVR (personal video recorder) - Watch Digital Tv, Analogue Tv or High Definition Tv - Record Tv Shows to the Hard Drive - Pause/Rewind Live Tv
• Information Services - Surf the web - Worldwide News Reports - Weather Reports from any city in the world
• Store and Play MP3's
• Store and Play compressed video files (avi, qt, mpeg etc)
• Play DVD's/VCD's
• Import/Rip DVD's
• Store and Browse your photo library (jpeg's, bmp's etc)
• Play Games (SNES, NES, Arcade Games - using 'emulators')

Quick Start Guide

Remote Commands

The Function Keys F1 - F6 can be programed to custom functions with MythWeb.

Keyboard Commands

Keyboard Commands allow a much more detailed control of MythTV than the IR Remote does. More Keys. :-) The keys.txt file describes what the various keyboard commands are. If you have loaded mythweb, you may change the default keys to your liking.

mythfrontend

Watching TV or a recording

Watching TV only

LiveTV Browse Mode

Playback Recording Zoom Mode

If you have two or more tuner cards

Watching a recording only

EPG

Setting Program or Channel Recording Priorities

Viewing Scheduled Recordings/Resolving Conflicts

Viewing Search Listings

Recording Profiles Setup Screen

Recording Groups

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.

Watch Recordings Screen

Administrative Information

Scheduling Recordings.

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 the shows. 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 express your preference. Further, the "Upcoming Recordings" page allows you make specific decisions about what you really do and don't want to record.

Record Types

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.

• 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 is 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Channel Record -- records a show anytime the title is listed on this station. This is perhaps the most common rule to use for most shows.
• Record All -- record this title on any channel at any time. 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.

Scheduling Options

Priority

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 all 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" to have a unique value so the scheduler can always 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 four different priority factors. By default, most of these factors are "0" but you may use any combination to express your likes and needs.

Per record rule -- this is the "priority" field in the "Scheduling Options" section of the options page and this values 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.

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 regular shows and will be more likely to record in a non-conflicting time instead. The default is -1.

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.

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 another card. 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 station whenever possible but the station on the analog input could still be used when the digital input is busy.

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 shows 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 Auto-Expire, below).

Duplicates

Singles will record without regard to duplicate matching.

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.

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.

Conflicts

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.

Scheduling decisions

Here are the actual decisions made by the scheduler as it fills in the schedule.

• 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.
• Single showing rules with no match are marked Not Listed -- If a Single or Override 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.
• Other record statuses beat Inactive or Repeat -- If two rules match the same showing of a program, a rule marked as inactive or a showing marked as a repeat yield to the other rule.
• 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.
• 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.
• 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, start recording now 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.
• 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.
• If both start times have passed, later start time beats earlier start time -- This attempts to miss the least amount of time.
• 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.
• 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.
• 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.
• 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.

Reschedule Higher Priorities

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".

Controlling Your Schedule

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.

Storage Options

Recording Profile

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 Recording, above).

 Recording Group

For organization of the "Watch Recordings" screen and the MythWeb interface, recordings can be assigned into "recording groups".

 Playback Group

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.

 Auto-Expire

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.

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.

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.

Episode Limit

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.

Post Recording Processing

Commercial Flagging

Select whether or not to automatically flag commercials for these recordings. Commercial Flagging parameters can be set in Setup->TV Settings->General.

Transcoding

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 Recording, above.

User Jobs

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:

• %DIR% - the directory component of the recording's filename
• %FILE% - the filename component of the recording's filename
• %TITLE% - the title of the recording (e.g., name of the series)
• %SUBTITLE% - the subtitle of the recording (e.g., name of the episode)
• %DESCRIPTION% - description text for the recording (from guide data)
• %HOSTNAME% - the backend making the recording
• %CATEGORY% - the category of the recording (from guide data)
• %RECGROUP% - the recording group
• %CHANID% - the MythTV channel ID making the recording
• %STARTTIME% - the recording start time (YYYYMMDDhhmmss)
• %ENDTIME% - the recording end time (YYYYMMDDhhmmss)
• %STARTTIMEISO% - the recording start time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
• %ENDTIMEISO% - the recording end time in ISO 8601 format
• %PROGSTART% - the recording's start time (from guide data; YYYYMMDDhhmmss)
• %PROGEND% - the recording's end time (from guide data)
• %PROGSTARTISO%, %PROGENDISO% - the recording's start and end time in ISO 8601 format.

Advanced Recording Options

Creating Power Search rules with Custom Record

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.

Getting Started

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:

     program.title = 'Nova'

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. With MythTV version 0.19 or later, 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:

            program.title = 'Nova'
            AND HOUR(program.starttime) >= 19
            AND HOUR(program.starttime) < 23

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".

How it Works

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 fields 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 field 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.

Common Tricks and Tips

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".

       program.title = "Celebrity Poker Showdown"
       AND program.previouslyshown = 0

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.

       program.title LIKE "Celebrity Fit Club%"
       AND DAYNAME(program.starttime) = "Sunday"

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%".

Working with SQL

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 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 fields, you can get a more complete list of all the fields that are available by using a MySQL client program:

$ mysql -u mythtv -pmythtv mythconverg
mysql> describe program;
mysql> describe channel;

• "program.category_type" holds one of these exact four strings: "movie", "series", "sports" or "tvshow".
• "program.airdate" is a string representing the year of release for movies and may have no meaning for other types of shows.
• "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.
• "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".
• "program.previouslyshown" is a field 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.
• "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. Detailed information can be found in the Data Direct documentation at http://labs.zap2it.com/.

Finally, if you are doing something very experimental and a field is not giving you the results you had anticipated, you can always check the MythTV source code to see exactly how a field is used. The open source for MythTV is available from http://www.mythtv.org/ .

Watching a DVD or VCD

Ripping a DVD

MythVideo

MythMusic

MythMusic is fairly simple to use. It is recommended that you insert the CD before selecting "Import CD".

Playlist Management

• Create a playlist. 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.
• Edit a playlist. 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.
  • Rearrange the songs in a playlist. 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.
  • Delete an item from a playlist. Highlight the item in the selection tree and hit the "d" key.
  • Edit a text field without a keyboard. (This applies to all of MythTV's UI and is not specific to MythMusic.)
    • 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.
    • Press ENTER in the empty line edit control. A keyboard will pop up; you can use this keyboard to enter characters.
• Delete a playlist. Highlight the playlist in the selection tree and hit the "i" key then select "Delete this Playlist" from the popup.

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 (ie. 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.

Useful keys to know

• some keyboard commands that might come in handy..
  • Change visualisation mode - 6
  • Blank Screen - 5
  • Increase track rating - 9
  • Decrease track rating - 7
  • Refresh music tree - 8
  • Filter all my music - F
  • Show incremental search dialog - CTRL + S
  • Incremental search find next match - CTRL + N
  • (note these are based on the default key mappings)

You may run into errors when running MythMusic.

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 ( /home/mythtv )  and type:

rm .cdserverrc

rm -rf .cddb/

These files aren't automatically deleted because of a conscious design decision by the author that programs that automatically delete things are bad.

MythGallery

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:

• 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.
• Rotate CW - Rotate the current image 90 degrees in the clockwise direction. This change persists if the current directory is writable.
• Rotate CCW - As above except the direction of rotation is counter(anti) clockwise.
• Import - Import pictures into your Gallery Dir. This option is described in the next section.
• Settings - Access the MythGallery settings screen.

Importing Pictures

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 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 smbclient 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:

#!/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

MythWeather

These are the keyboard commands for MythWeather:

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

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 mythweather --debug

You may also force mythweather to re-run the configuration by starting it on the command line as mythweather --configure. These two options are mutually exclusive.

MythPhone

User Guide - How To Get Started

MythNews

MythBrower  

jstest /dev/js0

jscal -c /dev/js0

jscal -t /dev/js0 ,

jscal -p /dev/js0

[startup] {jscal -s 6,1,1,...}

MythArchive

MythFlix

MythWeb

Resetting the key binding table

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:

$ echo "delete from keybindings ;" | mysql -u mythtv -pmythtv mythconverg

Resetting the theme.

If you find yourself wedged into a theme that isn't working, open your web browser and go to site: http://mythweb_name_or_ip_address/mythweb/settings.php?RESET_THEME=yes

Advanced Setup Topics

 Adding DishTV information to the database

A script for adding Pay Per View information into the MythTV database for DishTV subscribers is available at http://www.mythppv.com/.

Adding support for an external tuner

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 /usr/local/bin/changechannel to your Input Connections in the mythbackend configuration GUI.

However, there is not changechannel program per-se, because this is going to be dependent on what sort of external tuner you have. Look in the contrib/channel_changers directory for a number of programs and scripts which may be used to change channels. Once you find one which works, copy it to /usr/local/bin/changechannel.

Feel free to browse some of what sort of hardware is available at http://store.snapstream.com/accessories.html, or if you wish to assemble your own, rather than purchase, the following may be helpful: http://www.dtvcontrol.com/ for cable pinouts.

Using Shutdown/Wakeup

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:

• 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.
• Use your motherboard's BIOS wakeup capability. You'll need a motherboard that supports BIOS wakeup, and some tools. Two that work are: http://sourceforge.net/projects/nvram-wakeup and http://www.malloc.de/tools/wakeup_clock.html

A deeper look into the operation

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.

• no client is connected to the server
• no recording (neither LiveTV nor a regular recording) is currently taking place
• no recording starts within a definable amount of time ("Max. wait for recording (min)")
• the "pre Shutdown check-command" returns 0

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.

Setting up the MythTV side of this extension.

There are a number of options that are used to control the Shutdown / Wakeup feature.

Shutdown/Wakeup Options:

• "Idle timeout (secs)" is the time the server waits while idle until a shutdown occurs.
• "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.
• "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.
• "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".
• "Set wakeuptime command" is the command executed to set the new wakeuptime.
• "Server Halt Command" is the command executed to shutdown the Master backend and the Slave backends.
• "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:
  • If it returns a "0" the shutdown will occur as scheduled.
  • If it returns a "1" the "idle timeout" will be reset and the system waits again for the timeout.
  • 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.

The "WakeOnLan settings": These settings have nothing to do with using BIOS or WOL wakeup, they are the same for both.

• "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.
• "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.
• "Wake command for slaves" is the one command executed to wake your Slave backends. This should be a script that contains the calls to wakeup all Slave backend systems.

Using WOL to wake your Master backend.

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:

#! /bin/sh
echo $@ | nc $SERVER $PORT

If you use inetd:

In /etc/inetd.conf add:

mythwake stream tcp nowait mythtv /usr/sbin/tcpd /usr/local/bin/mythwake

service mythwake
  {    
        socket_type     = stream
        wait            = no
        user            = mythtv        
        protocol        = tcp
        id              = mythwake
        server          = /usr/local/bin/mythwake
  }

mythwake        $PORT/tcp

Finally, /usr/local/bin/mythwake looks like:

#! /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 ;

Using BIOS wakeup to wake your Master backend.

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.

Wakeup the MySQL server using WOL

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 mysql.txt. The meanings are the same as discussed in "The WakeOnLan settings" above.

Tips/Tricks:

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 /sbin/shutdown -t TIMEOUT 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 /sbin/shutdown -c.

If you get "nvram-wakeup: /dev/rtc: Device or resource busy" your set-wakeuptime-script should stop the program that uses /dev/rtc before setting the wakeuptime.

Controlling the mythfrontend via telnet

New in 0.19 is the capability to control the mythfrontend using telnet commands. To use this feature you must first enable it in Settings>General>General

The network control listens on port 6546, as demonstrated below:

$ 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
$

Please note that this feature only allows one connection at a time, so any new connections will automatically terminate prior ones.

Adding DishTV information to the database

A script for adding Pay Per View information into the MythTV database for DishTV subscribers is available at http://www.mythppv.com/.

Adding support for an external tuner

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 /usr/local/bin/changechannel to your Input Connections in the mythbackend configuration GUI.

However, there is not changechannel program per-se, because this is going to be dependent on what sort of external tuner you have. Look in the contrib/channel_changers directory for a number of programs and scripts which may be used to change channels. Once you find one which works, copy it to /usr/local/bin/changechannel.

Feel free to browse some of what sort of hardware is available at http://store.snapstream.com/accessories.html, or if you wish to assemble your own, rather than purchase, the following may be helpful: http://www.dtvcontrol.com/ for cable pinouts.

Grabbing channel icons for DataDirect users

While the DataDirect 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 contrib/ directory which will generate this file for you. Run the command:

$ perl mkiconmap.pl

You will be asked for your zip code and the service that you use. If there are no errors, the iconmap.xml 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 contrib/master_iconmap.xml 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 iconmap.xml file, add the icon information to your database and grab any new icons with the command:

$ mythfilldatabase --import-icon-map iconmap.xml --update-icon-map
  

Removing unwanted channels

If mythfilldatabase 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 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 ~/.mythtv/<sourcename>.xmltv file by inserting the word "not " (including the space) in front of the unwanted entry. This will prevent xmltv 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 chanid used by MySQL:

$ 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;

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:

$ mysql -u root mythconverg

mysql> delete from program where chanid = 1015;

What do the icons on the Watch Recordings screen mean?

Press "1" or F1 to get a popup.

What do the letters mean when I change channels?

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

l/L = Lock : This could be seen by PVR-250/BTTV users a/A = PAT : Any recording transmitted in MPEG m/M = PMT : Any recording transmitted in MPEG g/G = MGT : ATSC only v/V = VCT : ATSC only n/N = NIT : DVB only s/S = SDT : DVB only

Changing channels on an external Set Top Box

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:

1. 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.
2. 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.
3. Use a firewire connection. There is a 6200ch.c in the MythTV contrib directory which may work for you.

LBMC Blaster codesets

The format of the key names in the supplied lircd.conf that includes all of the codesets is DEVICE_CODESET_KEY, for example 1_680_KEY_POWER.

Device is either 0 (for cable box) or 1 (for satellite). For other key names look in lircd.conf. (Various devices have different keys).

For example, if you have a Motorola DCT 2000 cable box, this would be 0_82_KEY_POWER. If you have a Hughes Satelittle box, this would be 1_82_KEY_POWER.

Also note that not all devices are listed -- this is just what the hauppauge software has. Many devices will work with more than one codeset, and many unlisted devices will work with one or more codesets. It is recommended that you try scanning if looking up the device is not possible (because it is missing), or the listed codeset does not work.

If the blaster LED flashes, but the device fails to respond to any listed codeset, then there is a good chance that the device simply is not supported. If you want support, you first need to check that it does not work under Windows, and then bug Hauppauge about it. I am only capable of supporting the same devices as the Windows software -- because the codeset database is encrypted, I cannot modify it.

North America, Cable Box

North America, Satellite

Europe, Cable Box

Europe, Satellite

Hauppauge, Satellite

Nvidia Setup

    1.  Introduction
    2.  Layout of the nvidia-settings GUI
    3.  How OpenGL Interacts with nvidia-settings
    4.  Loading Settings Automatically
    5.  Commandline Interface
    6.  X Display Names in the Config File
    7.  Connecting to Remote X Servers
    8.  Licensing
    9.  TODO


1.  Introduction

    The `nvidia-settings` utility is a tool for configuring the NVIDIA
    Linux graphics driver.  It operates by communicating with the NVIDIA
    X driver, querying and updating state as appropriate.  This
    communication is done with the NV-CONTROL X extension.

    Values such as brightness and gamma, XVideo attributes, temperature,
    and OpenGL settings can be queried and configured via nvidia-settings.

    When nvidia-settings starts, it reads the current settings from
    its configuration file and sends those settings to the X server.
    Then, it displays a graphical user interface (GUI) interface for
    configuring the current settings.  When nvidia-settings exits, it
    queries the current settings from the X server and saves them to
    the configuration file.



2.  Layout of the nvidia-settings GUI

    The nvidia-settings GUI is organized with a list of different
    categories on the left side.  Only one entry in the list can be
    selected at once, and the selected category controls which
    "page" is displayed on the right side of the nvidia-settings GUI.

    The category list is organized in a tree: each X screen contains
    the relevant subcategories beneath it.  Similarly, the Display
    Devices category for a screen contains all the enabled display
    devices beneath it.  Besides each X screen, the other top level
    category is "nvidia-settings Configuration", which configures
    behavior of the nvidia-settings application itself.

    Along the bottom of the nvidia-settings GUI, from left to right, is:
    1) a status bar which indicates the most recently altered option;
    2) a Help button that toggles the display of a help window which
    provides a detailed explanation of the available options in the
    current page; and 3) a Quit button to exit nvidia-settings.

    Most options throughout nvidia-settings are applied immediately.
    Notable exceptions are OpenGL options which are only read by OpenGL
    when an OpenGL application starts.

    Details about the options on each page of nvidia-settings are
    available in the help window.



3.  How OpenGL Interacts with nvidia-settings

    When an OpenGL application starts, it downloads the current values
    from the X driver, and then reads the environment (see APPENDIX E:
    OPENGL ENVIRONMENT VARIABLE SETTINGS in the README).  Settings from
    the X server override OpenGL's default values, and settings from
    the environment override values from the X server.

    For example, by default OpenGL uses the FSAA setting requested by
    the application (normally, applications do not request any FSAA).
    An FSAA setting specified in nvidia-settings would override
    the OpenGL application's request.  Similarly, the __GL_FSAA_MODE
    environment variable will override the application's FSAA setting,
    as well as any FSAA setting specified in nvidia-settings.

    Note that an OpenGL application only retrieves settings from the X
    server when it starts, so if you make a change to an OpenGL value
    in nvidia-settings, it will only apply to OpenGL applications which
    are started after that point in time.



4.  Loading Settings Automatically

    The NVIDIA X driver does not preserve values set with nvidia-settings
    between runs of the X server (or even between logging in and logging
    out of X, with xdm, gdm, or kdm).  This is intentional, because
    different users may have different preferences, thus these settings
    are stored on a per user basis in a configuration file stored in
    the user's home directory.

    The configuration file is named "~/.nvidia-settings-rc".  You can
    specify a different configuration file name with the "--config"
    commandline option.

    After you have run nvidia-settings once and have generated a
    configuration file, you can then run:

        nvidia-settings --load-config-only

    at any time in the future to upload these settings to the X
    server again.  For example, you might place the above command in
    your ~/.xinitrc file so that your settings are applied automatically
    when you log in to X.

    Your .xinitrc file, which controls what X applications should
    be started when you log into X (or startx), might look something
    like this:

        nvidia-settings --load-config-only &
        xterm &
        evilwm

    or:

        nvidia-settings --load-config-only &
        gnome-session

    If you do not already have an ~/.xinitrc file, then chances are that
    xinit is using a system-wide xinitrc file.  This system wide file
    is typically here:

        /etc/X11/xinit/xinitrc

    To use it, but also have nvidia-settings upload your settings,
    you could create an ~/.xinitrc with the contents:

        nvidia-settings --load-config-only &
        . /etc/X11/xinit/xinitrc

    System administrators may choose to place the nvidia-settings load
    command directly in the system xinitrc script.

    Please see the xinit(1) manpage for further details of configuring
    your ~/.xinitrc file.



5.  Commandline Interface

    nvidia-settings has a rich commandline interface: all attributes
    that can be manipulated with the GUI can also be queried and set from
    the command line.  The commandline syntax for querying and assigning
    attributes matches that of the .nvidia-settings-rc configuration file.

    The "--query" option can be used to query the current value of
    attributes.  This will also report the valid values for the attribute.
    You can run `nvidia-settings --query all` for a complete list of
    available attributes, what the current value is, and what values
    are valid for the attribute.  Additionally, individual attributes
    may be specified like this:

        nvidia-settings --query CursorShadow

    Attributes that may differ per display device (for example
    DigitalVibrance can be set independently on each display device
    when in TwinView) can be appended with a "display device name"
    within brackets; eg:

        nvidia-settings --query DigitalVibrance[CRT-0]

    If an attribute is display device specific, but the query does not
    specify a display device, then the attribute value for all display
    devices will be queried.

    An attribute name may be prepended with an X Display name and a
    forward slash to indicate a different X Display; eg:

        nvidia-settings --query 192.168.1.33:0.0/DigitalVibrance[DFP-1]

    An attribute name may also just be prepended with the screen number
    and a forward slash:

        nvidia-settings --query 0/DigitalVibrance[DFP-1]

    in which case the default X Display will be used, but you can indicate
    to which X screen to direct the query (if your X server has multiple
    X screens).  If no X screen is specified, then the attribute value
    will be queried for all X screens.


    The "--assign" option can be used to assign a new value to an
    attribute.  The valid values for an attribute are reported when the
    attribute is queried.  The syntax for --assign is the same as --query,
    with the additional requirement that assignments also have an equal
    sign and the new value.  For example:

        nvidia-settings --assign FSAA=2
        nvidia-settings --assign 0/DigitalVibrance[CRT-1]=9


    Multiple queries and assignments may be specified on the commandline
    for a single invocation of nvidia-settings.

    If either the --query or --assign options are passed to
    nvidia-settings, the GUI will not be presented, and nvidia-settings
    will exit after processing the assignments and/or queries.

    

6.  X Display Names in the Config File

    In the Commandline Interface section above, it was noted that you
    can specify an attribute without any X Display qualifiers, with only
    an X screen qualifier, or with a full X Display name.  For example:

        nvidia-settings --query FSAA
        nvidia-settings --query 0/FSAA
        nvidia-settings --query stravinsky.nvidia.com:0/FSAA

    In the first two cases, the default X Display will be used, in the
    second case, the screen from the default X Display can be overridden,
    and in the third case, the entire default X Display can be overridden.

    The same possibilities are available in the ~/.nvidia-settings-rc
    configuration file.

    For example, in a computer lab environment, you might log into any
    of multiple workstations, and your home directory is NFS mounted
    to each workstation.  In such a situation, you might want your
    ~/.nvidia-settings-rc file to be applicable to all the workstations.
    Therefore, you would not want your config file to qualify each
    attribute with an X Display Name.  Leave the "Include X Display Names
    in the Config File" option unchecked on the nvidia-settings Configuration
    page (this is the default).

    There may be cases when you do want attributes in the config file to
    be qualified with the X Display name.  If you know what you are doing
    and want config file attributes to be qualified with an X Display,
    check the "Include X Display Names in the Config File" option on the
    nvidia-settings Configuration page.

    In the typical home user environment where your home directory is
    local to one computer and you are only configuring one X Display,
    then it does not matter whether each attribute setting is
    qualified with an X Display Name.



7.  Connecting to Remote X Servers

    nvidia-settings is an X client, but uses two separate X connections:
    one to display the GUI, and another to communicate the NV-CONTROL
    requests.  These two X connections do not need to be to the same
    X server.  For example, you might run nvidia-settings on the
    computer stravinsky.nvidia.com, export the display to the computer
    bartok.nvidia.com, but be configuring the X server on the computer
    schoenberg.nvidia.com:

        nvidia-settings --display=bartok.nvidia.com:0 \
            --ctrl-display=schoenberg.nvidia.com:0

    If "--ctrl-display" is not specified, then the X Display to control
    is what "--display" indicates.  If "--display" is also not specified,
    then the $DISPLAY environment variable is used.

    Note, however, that you will need to have X permissions configured
    such that you can establish an X connection from the computer on
    which you are running nvidia-settings (stravinsky.nvidia.com) to the
    computer where you are displaying the GUI (bartok.nvidia.com) and the
    computer whose X Display you are configuring (schoenberg.nvidia.com).

    The simplest, most common, and least secure mechanism to do this
    is to use 'xhost' to allow access from the computer on which
    you are running nvidia-settings.  

        (issued from bartok.nvidia.com)
        xhost +stravinsky.nvidia.com

        (issued from schoenberg.nvidia.com)
        xhost +stravinsky.nvidia.com

    This will allow all X clients run on stravinsky.nvidia.com to
    connect and display on bartok.nvidia.com's X server and configure
    schoenberg.nvidia.com's X server.

    Please see the xauth(1) and xhost(1) manpages, or refer to your Linux
    Distribution's documentation on remote X applications and security.
    You might also google for terms such as "remote X security" or "remote
    X Windows", and see documents such as the Remote X Apps mini-HOWTO:

        http://www.tldp.org/HOWTO/Remote-X-Apps.html

    Please also note that the remote X server to be controlled must
    be using the NVIDIA X driver.



8.  Licensing

    The source code to nvidia-settings is released as GPL.  The most
    recent official version of the source code is available here:

        ftp://download.nvidia.com/XFree86/nvidia-settings/

    Note that nvidia-settings is simply an NV-CONTROL client.  It uses
    the NV-CONTROL X extension to communicate with the NVIDIA X server
    to query current settings and make changes to settings.

    You can make additions directly to nvidia-settings, or write your
    own NV-CONTROL client, using nvidia-settings as an example.

    Documentation on the NV-CONTROL extension and additional sample
    clients are available in the nvidia-settings source tarball.

    Patches can be submitted to linux-bugs@nvidia.com.



9.  TODO

    There are many things still to be added to nvidia-settings.  Some of
    which include:

    - configurability of TwinView (NVIDIA is planning to implement this)

    - configurability of multiple X screens (NVIDIA is planning to
      implement this)

    - different toolkits?  the GUI for nvidia-settings is cleanly
      abstracted from the backend of nvidia-settings that parses
      the configuration file and commandline, communicates with the X
      server, etc.  If someone were so inclined, a different frontend
      GUI could be implemented.

    - write a design document explaining how nvidia-settings is
      architected; presumably this would make it easier for people to
      become familiar with the code base.

    If there are other things you would like to see added (or better yet,
    would like to add yourself), please contact linux-bugs@nvidia.com.