Next Previous Contents

## 12. 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.

## 12.1 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.

## 12.2 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 preference -- in the MythTV "setup" program, the "Input Connections" section allows you to add additional priority in the "Input preference". 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 card rather than a showing on another card. If you have multiple cards of different quality, you may want to set input preference 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.

## 12.3 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.

## 12.4 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.

## 12.5 Advanced Recording Options

### Creating Power Search rules with Custom RecordMythTV's "Custom Record" feature gives you unlimited control for creatingspecialized search recording rules to meet your needs. It allows you tochoose your criteria to search for matching shows based on any of theinformation in the program listings, channel information, time functions andmore. This goes beyond the capabilities of any other DVR system and it isunlikely that this level of scheduling customization will ever be availablein 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'

> `

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

> `

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

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

> `

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.

> `

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

> `

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

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

> `

This will show the names of all of the fields 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.

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

Next Previous Contents