mythtv/docs/mythtv-HOWTO-12.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
 <TITLE>Installing and using MythTV: Scheduling Recordings.</TITLE>
 <LINK HREF="mythtv-HOWTO-13.html" REL=next>
 <LINK HREF="mythtv-HOWTO-11.html" REL=previous>
 <LINK HREF="mythtv-HOWTO.html#toc12" REL=contents>
</HEAD>
<BODY>
<A HREF="mythtv-HOWTO-13.html">Next</A>
<A HREF="mythtv-HOWTO-11.html">Previous</A>
<A HREF="mythtv-HOWTO.html#toc12">Contents</A>
<HR>
<H2><A NAME="s12">12.</A> <A HREF="mythtv-HOWTO.html#toc12">Scheduling Recordings.</A></H2>

<P>The MythTV master backend is responsible for managing the schedule for
all TV tuner cards on the master and any slave. Its job is to search the TV
listing for the shows you have requested and assign recordings to the TV
tuner cards. If none of the shows that you've chosen overlap, it simply
records all of them. However, if there are shows where the beginning
and end times overlap, the scheduler follows rules that you've specified or
makes logical decisions about what would be best if you haven't expressed your
preference. Further, the "Upcoming Recordings" page allows you make specific
decisions about what you really do and don't want to record.</P>

<H2><A NAME="ss12.1">12.1</A> <A HREF="mythtv-HOWTO.html#toc12.1">Record Types</A>
</H2>

<P>When you choose a show that you would like to record from the
Options Page, there are eight different types of rules to help the
scheduler find which showings you would like to record.</P>
<P>
<UL>
<LI>Single Record -- record only this title at this specific time and
this station. This is the best way to be sure that a certain showing will
be recorded. However, if the TV listings change and the show is not broadcast
at that time, the show will not be recorded but will be marked as Not Listed
to let you know that you should investigate.
</LI>
<LI>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.
</LI>
<LI>Record Weekly -- this records a show whenever the title is listed
on the same channel, weekday and time. Note that if the TV station
changes the schedule for a special episode, it would not be
recorded. However, you can add a Single record for the special
episode. If there are no matching showings in the TV listings,
a Not Listed item will be added to your schedule for the next
time slot to let you know that you should investigate.
</LI>
<LI>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.
</LI>
<LI>Record Daily -- this records a show whenever the title is listed
for the time and station on any day of the week. Here again, a show
will not be recorded if the time was altered by the station. If there
are no matching showings in the TV listings, a Not Listed item will be
added to your schedule for the next time slot to let you know that you
should investigate.
</LI>
<LI>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.
</LI>
<LI>Channel Record -- records one showing of each unique episode from
any of the times the title is listed on this station.  This is perhaps
the most common rule to use for most shows.
</LI>
<LI>Record All -- records one showing of each unique episode from
any of the times this title is listed on any channel. This can be
useful if a station has sister stations where shows are rebroadcast
allowing the scheduler to record rebroadcasts on the other station
when the original airing cannot be recorded.</LI>
</UL>
</P>

<H2><A NAME="ss12.2">12.2</A> <A HREF="mythtv-HOWTO.html#toc12.2">Scheduling Options</A>
</H2>

<H3>Priority</H3>

<P>By default, all shows you select have equal value to the
scheduler.  There are a set of rules to make good choices when
two or more shows are in conflict. However, priority values let the
scheduler know what you prefer so that it can set the schedule based
on your preferences.</P>
<P>Initially, recording rule priority values are set to zero. You may choose
to leave everything at "0" and let the scheduler follow rules to guess
what you might prefer when there are conflicts. However, if you have
one or two favorite shows, you may want to increase the priority
value so the scheduler will know that you would prefer recording
these over other shows. You might use certain values to rate shows
so that all favorites are 2. good shows are 1 and extra 'filler'
shows are all -1 for example. You could sort each title on the "Set
Priorities" page to have a unique value so the scheduler can know
which show you'd prefer versus any other show. The choice and style
are entirely up to you. However, the more information you give to
the scheduler, the more likely it will make the choices you would
prefer in the first place.</P>
<P>The scheduler choices are based on the total priority for a showing by
adding up all priority factors that match the showing. By default, most
of these factors are "0" but you may use any combination to express your
likes and needs.</P>
<P>
<UL>
<LI>Per record rule -- this is the "priority" selection in the "Scheduling
Options" section of the options page and this value is included for any
showings that match the recording rule.  You may choose to only use these
values and not use the other factors for the sake of simplicity and clarity.</LI>
<LI>Per record type -- Setup->TV Settings->Recording Priorities->General allows
you to add to the priority based on the type. It may make sense to increase
the value for "Single" so that by default they have an extra advantage over
other shows. The default is +1. You may want to decrease the value for Find
rules so that they will be less likely to interfere with regularly scheduled
shows and will be more likely to record in a non-conflicting time instead.
The default is -1.</LI>
<LI>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.</LI>
<LI>Input priority -- in the "mythtv-setup" program, the "Input Connections"
section allows you to add additional priority in the "Input priority".
This is simply another priority factor but has an interesting effect. If a
card input has a higher value than the other cards, the scheduler will see
that you would rather record showings of episodes on this input rather than a
showing on other inputs. If you have multiple cards of different quality,
you may want to set input priority to encourage the scheduler to record
shows on your best card(s) whenever possible. This can also be useful if you
have multiple video sources which include the same stations. For example,
with digital and analog cable you could increase the digital cable input
preference by 1 to tell the scheduler that you want to record from the
digital channel whenever possible but the channel on the analog input could
still be used when the digital input is busy.</LI>
<LI>Custom Priority -- this allows you to add any specialized factors you
would like in order to influence scheduling decisions. See the 
<A HREF="#Custom Priority">Custom Priority</A> section below.</LI>
</UL>

For any single showing of any show you've chosen to record, these factors
are added together to find the "total priority". This is the priority that
the scheduler uses to decide which showings are given the first choice when
filling in the schedule.</P>
<P>The scheduling priority of a show may also be used to determine
auto-expiration of recordings when disk space gets full (see 
<A HREF="#Auto-Expire">Auto-Expire</A>, below).</P>

<H3>Duplicates</H3>

<P>Singles will record without regard to duplicate matching.</P>

<P>The standard recurring methods of All, Channel, Weekly and Daily use the
descriptive information in the TV listings to try to record only one showing
of each unique episode. However, This goal is sometimes complicated by the
fact that the stations may not include a description for a specific episode
but use a generic description for the series instead. When there is a
generic description, the default behavior is to assume that it may be an
episode that you have not seen and to record it for you.  One of the
duplicate matching options is "Record new episodes only".  If this is
selected, listing that have an original air date of more than 14 days
earlier are considered repeats and are not eligible to record. Generally,
generic episodes will be marked as repeats also.</P>

<P>Because of generic episodes and other situations, MythTV offers an
alternative approach where shows may be recorded by choosing from multiple
showings even when the descriptive information is not reliable. All of the
"Find" record types look for matching titles in the listings. If there is a
showing with specific episode information and that episode has recorded
before, that showing is marked as previously or currently recorded. The
scheduler will then choose to record the earliest non-conflicting showing
from any of other remaining showings regardless of the descriptive
information. Generally, Find One is most useful for movies or specials and
the Find Daily and Find Weekly rules are best for news or current events
shows that are repeated. However, these may be useful in other situations
where the standard recording rules may not work correctly.</P>

<H3>Conflicts</H3>

<P>As you add more shows that you would like to record, the scheduler
will eventually encounter conflicts. If there are two shows at the
same time and you have two or more TV tuner cards, both shows will
record. However, if there are more shows than cards, the scheduler
will have to decide what it thinks it should not record based on the
information you have given. If you see an unexpected situation you
are not "stuck" with the scheduler's choice. You can still tell the
scheduler exactly which shows you do want to record and/or don't
want to record in any situation.</P>

<H3>Scheduling decisions</H3>

<P>Here are the actual decisions made by the scheduler as it fills in the
schedule.</P>
<P>
<UL>
<LI>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.
</LI>
<LI>Single, Daily, or Weekly rules with no match are marked Not Listed -- 
If these or Overrides do not match the current listings because the
listings have changed, they are added to the schedule and marked to
indicate that they will not record.
</LI>
<LI>Rules that could record beat rules that can not record a showing --
If two rules match the same showing of a program, a rule marked as inactive
or a showing marked as a repeat, for example, yield to the other rule.
</LI>
<LI>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.
</LI>
<LI>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.
</LI>
<LI>Future start time beats past start time -- If there is an
episode in progress and also a later showing of the same episode, it
is better to record the complete episode. If there isn't another
showing, it will start recording immediately to record the remaining
portion. This should only happen if you add a new rule while the show
is in progress or if the master backend is started after the start time
of a scheduled show.
</LI>
<LI>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.
</LI>
<LI>If both start times have passed, later start time beats earlier start
time -- This attempts to miss the least amount of time.
</LI>
<LI>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.
</LI>
<LI>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.
</LI>
<LI>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.
</LI>
<LI>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.
</LI>
</UL>
</P>

<H3>Reschedule Higher Priorities</H3>

<P>Setup->TV Settings->Recording Priorities->General has a checkbox for
"Reschedule Higher Priorities" which tells the scheduler to try to be a
little smarter in certain situations. If this is checked, the scheduler will
look for situations where a show cannot record because all inputs for the
channel are used for higher priority shows. It will check to see if any of
the other shows could be recorded at another time so that the conflicting
show can be recorded in its place.</P>
<P>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.</P>
<P>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".</P>

<H3>Controlling Your Schedule</H3>

<P>The Manage Recordings->Upcoming Recordings page is your control center
for the MythTV scheduler. Unlike other DVR systems, this one page gives you
all of the information and tools you need to see all of your alternatives
and make whatever adjustments you desire.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>

<H2><A NAME="ss12.3">12.3</A> <A HREF="mythtv-HOWTO.html#toc12.3">Storage Options</A>
</H2>

<H3>Recording Profile</H3>

<P>Each recording rule can be configured with a different recording
profile.  For example, colorful cinematography can be configured with a
"High Quality" profile, while 'talking heads' interviews shows can be
configured with a "Low Quality" profile. These recording profiles need to
be configured before using them (see 
<A HREF="mythtv-HOWTO-10.html#Recording">Recording</A>,
above).</P>

<H3><A NAME="Recording Group"></A> Recording Group </H3>

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

<H3><A HREF="mythtv-HOWTO-9.html#storagegroups">Storage Groups</A></H3>

<P>This allows you to select any special "Storage Groups" you may have
created to determine where recordings from this rule should be stored
on your disks. The "Default" storage group is always available.</P>

<H3><A NAME="Playback Group"></A> Playback Group </H3>

<P>This selects a set of pre-configured playback parameters which can be
created and edited in Setup->TV Settings->Playback Groups.  When the
recording is played, the values from this playback group will be
used. This allows you to choose a default time stretch value, skip and
jump amounts appropriate for this type of television program.</P>

<H3><A NAME="Auto-Expire"></A> Auto-Expire </H3>

<P>MythTV will "autoexpire" old recordings to make room for new recordings
when disk space gets filled up. This option can be set to "Don't allow
auto expire" to prevent these recordings from being automatically deleted
when disk space fills up.</P>

<P>The default setting is for all scheduled recordings to be eligible
for auto-expiration; this can be changed in the Settings->TV
Settings->General page by manipulating the "Auto Expire Default"
checkbox.</P>

<P>The default auto-expire policy is "Oldest Show First"; the oldest
recordings are deleted first. The "Lowest Priority First" method
chooses to expire the lowest-priority recordings first.</P>

<H3>Episode Limit</H3>

<P>An episode limit can also be configured to limit the maximum number
of episodes recorded of a single series, to restrict that series' disk
usage. If this is set, you can further decide what to do when this
limit is reached; either stop recording that series, or to delete the
oldest episodes in favor of the new ones.</P>

<H2><A NAME="ss12.4">12.4</A> <A HREF="mythtv-HOWTO.html#toc12.4">Post Recording Processing</A>
</H2>

<H3>Commercial Flagging</H3>

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

<H3>Transcoding</H3>

<P>Select whether or not to automatically transcode recordings to save
disk space. Before using this, you must first enable auto-transcode in
the recording profile and configure the transcoding parameters; see
<A HREF="mythtv-HOWTO-10.html#Recording">Recording</A>, above.</P>

<H3>User Jobs</H3>

<P>User Jobs allow you to configure up to 4 custom commands to run on
recordings. They can be configured in mythtv-setup. The following
tokens have special meaning when used in the User Job commands:</P>
<P>
<UL>
<LI>%DIR% - the directory component of the recording's filename</LI>
<LI>%FILE% - the filename component of the recording's filename</LI>
<LI>%TITLE% - the title of the recording (e.g., name of the series)</LI>
<LI>%SUBTITLE% - the subtitle of the recording (e.g., name of the
episode)</LI>
<LI>%DESCRIPTION% - description text for the recording (from guide
data)</LI>
<LI>%HOSTNAME% - the backend making the recording</LI>
<LI>%CATEGORY% - the category of the recording (from guide data)</LI>
<LI>%RECGROUP% - the 
<A HREF="#Recording Group">recording group</A></LI>
<LI>%CHANID% - the MythTV channel ID making the recording</LI>
<LI>%STARTTIME% - the recording start time (YYYYMMDDhhmmss)</LI>
<LI>%ENDTIME% - the recording end time (YYYYMMDDhhmmss)</LI>
<LI>%STARTTIMEISO% - the recording start time in ISO 8601 format
(YYYY-MM-DDTHH:MM:SS)</LI>
<LI>%ENDTIMEISO% - the recording end time in ISO 8601 format</LI>
<LI>%PROGSTART% - the recording's start time (from guide data;
YYYYMMDDhhmmss)</LI>
<LI>%PROGEND% - the recording's end time (from guide data)</LI>
<LI>%PROGSTARTISO%, %PROGENDISO% - the recording's start and end
time in ISO 8601 format.</LI>
</UL>
</P>

<H2><A NAME="ss12.5">12.5</A> <A HREF="mythtv-HOWTO.html#toc12.5">Advanced Recording Options</A>
</H2>

<H3>Creating Power Search rules with Custom Record</H3>

<P>MythTV's "Custom Record" feature gives you unlimited control for creating
specialized search recording rules to meet your needs. It allows you to
choose your criteria to search for matching shows based on any of the
information in the program listings, channel information, time functions and
more. This goes beyond the capabilities of any other DVR system and it is
unlikely that this level of scheduling customization will ever be available
in any commercial DVR system.</P>

<H3>Getting Started</H3>

<P>Go to Schedule Recordings->Custom Record. This page, helps you build a
database search one clause at a time. Each added clause further limits
which showings will be matched in the TV listings. You can test the
search at any time and when you are done, you can save your search as a
recording rule.</P>
<P>To familiarize yourself with how you can create custom rules, create a
simple rule to record "Nova" only in primetime.</P>
<P>The first item at the top of the page allows you to edit an existing rule
or create a new rule. Leave it on "&lt;New rule&gt;". 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:
<BLOCKQUOTE><CODE>
<PRE>
     program.title = 'Nova'
</PRE>
</CODE></BLOCKQUOTE>

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.</P>
<P>If you do not receive a PBS station that carries "Nova" or would like to use
another title, edit the title by pressing the down arrow to highlight the
text box and right arrow over the the word "Nova". If you are using a
keyboard you can simply delete the four letters and type a different title
between the quotes. With a remote control, you can do 'cell phone' style
text entry with the number pad. The delete key is the "X" in the grouping
for "1", zero is grouped with "9" and "0" acts as the "Caps Lock" key. You
can press ENTER in the text box to popup a virtual keyboard.</P>
<P>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.</P>
<P>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.</P>
<P>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:
<BLOCKQUOTE><CODE>
<PRE>
            program.title = 'Nova'
            AND HOUR(program.starttime) >= 19
            AND HOUR(program.starttime) &lt; 23
</PRE>
</CODE></BLOCKQUOTE>

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

<H3>How it Works</H3>

<P>MythTV stores TV program information in a database and uses the Structured
Query Language (SQL) to access the data. Information about each TV program
is stored in the 'program' table and information about each TV station you
receive is stored in 'channel'. These two tables are used in the scheduler
queries and their columns are available to be used in your rules. The rules
you create are stored in 'record'.</P>
<P>Normal rules in MythTV simply match the title in the rule with the titles
in the 'program' table. MythTV also has search rules for "Titles",
"Keywords" and "People". These store the key phrase in the description
column of the rule and includes them in specialized SQL replacements for
the normal title check. There is also a type called "Power Search" which
takes the raw SQL in the description as the replacement for title
matching.</P>
<P>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.</P>

<H3>Common Tricks and Tips</H3>

<P>The example clauses marked "complete example" are actual rules that have
been used to address specific problems. You may find that some of these
are useful for you as-is or with slight modifications. These show off how
powerful custom rules can be but there are also several simple idioms that
you may find useful for many of the shows you would like to record.</P>
<P>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.</P>
<P>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".
<BLOCKQUOTE><CODE>
<PRE>
       program.title = "Celebrity Poker Showdown"
       AND program.previouslyshown = 0
</PRE>
</CODE></BLOCKQUOTE>

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.</P>
<P>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.
<BLOCKQUOTE><CODE>
<PRE>
       program.title LIKE "Celebrity Fit Club%"
       AND DAYNAME(program.starttime) = "Sunday"
</PRE>
</CODE></BLOCKQUOTE>

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

<H3>Working with SQL</H3>

<P>As you experiment, it is possible that you may misplace a quote or mistype a
word. If there is a mistake when you press "Test" or "Record" you will see
an error message returned from the database. This will usually give you a
good idea about what needs to be fixed. However, for more subtle MySQL
syntax errors, you can find more information in the documentation at 
<A HREF="http://dev.mysql.com/doc/mysql/en/">http://dev.mysql.com/doc/mysql/en/</A>. 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.</P>
<P>While the example clauses demonstrate how to use many of the data columns,
you can get a more complete list of all the columns that are available by
using a MySQL client program:
<BLOCKQUOTE><CODE>
<PRE>
$ mysql -u mythtv -pmythtv mythconverg
mysql> describe program;
mysql> describe channel;
</PRE>
</CODE></BLOCKQUOTE>

This will show the names of all of the columns along with their type and
default value. Most are easy to understand but a few need some explanation
in order to use them effectively with Power Search.
<UL>
<LI>"program.category_type" holds one of these exact four strings: "movie",
"series", "sports" or "tvshow".
</LI>
<LI>"program.airdate" is a string representing the year of release for
movies and may have no meaning for other types of shows.
</LI>
<LI>"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.
</LI>
<LI>"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".
</LI>
<LI>"program.previouslyshown" is a column created by MythTV to try to
determine if a showing is more than 14 days after its original air date or
if the show was marked as a repeat and did not have a date for the first
airing. If this is "0" it usually means that this is a brand new show or a
rebroadcast within the first two weeks.
</LI>
<LI>"program.generic" is a column created by MythTV to try mark
showings for a series where the specific episode information is not
included. When these generic showings appear, it is impossible for the
system to determine if they are repeats of the same episode(s) or if
they are all different episodes.
</LI>
<LI>"program.first" is a column created by MythTV to mark the first
showing in the current listings for each episode, movie or special.
Choosing to match only the "first" showing can be useful for sports
that are brodcast live then repeated.
</LI>
<LI>"program.last" is a column created by MythTV to mark the last
showing in the current listings for each episode, movie or special.
If a showing is marked both "first" and "last" then it is the only
showing of that program in the current TV listings.
</LI>
<LI>"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.
</LI>
<LI>"program.videoprop" also "audioprop" and "subtitletypes".
These columns contain bit flags for a variety of attributes that
may be associated with a program. These are filled with information
offered by the TV listings provider. However, your listings source
will not have information for all of the available flags. Therefore,
some of these may not be useful for your search rules. This information 
is organized in "sets" and the MySQL function FIND_IN_SET() can be used
to test for any of these flags. For example:
<BLOCKQUOTE><CODE>
<PRE>
FIND_IN_SET('SURROUND', program.audioprop) > 0
</PRE>
</CODE></BLOCKQUOTE>

would be true for the programs where the surround sound bit is present.
To see all of the available attribute names:
<BLOCKQUOTE><CODE>
<PRE>
$ mysql -u mythtv -pmythtv mythconverg
mysql> SHOW COLUMNS FROM program LIKE '%prop'\G
mysql> SHOW COLUMNS FROM program LIKE 'subtitletypes'\G
</PRE>
</CODE></BLOCKQUOTE>
</LI>
</UL>

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

<H2><A NAME="ss12.6">12.6</A> <A HREF="mythtv-HOWTO.html#toc12.6">Scheduling with more than one Input</A>
</H2>


<P>MythTV is designed to allow recording television programs from one or more
service providers, or video source, on one or more video input from each
provider. Some inputs may not be allowed to record at the same time as
each other while others may record simultaneously.</P>
<P>A television station may be broadcast on more than one channel from one
provider or may be available on channels from two or more providers. If a TV
station is available from more than one source, the video quality or type of
broadcast may differ. Therefore, MythTV allows you to control how you would
like the scheduler to select the best channel and input for a show which is
available on more than one input or more than one channel.</P>

<H3>Mutually Exclusive Inputs</H3>

<P>A single TV capture card may have video connections to more than
one of its inputs and each input may be from a different service.  The card
may only be allowed to record from one of these inputs at one time because
there is only one encoder on the card that actually captures the content.</P>
<P>
<FIGURE>
<EPS FILE="BlockDiagramofavideocapturedevice.eps">
<IMG SRC="BlockDiagramofavideocapturedevice.png">
<CAPTION></CAPTION>
</FIGURE>
</P>
<P>These are mutually exclusive meaning that only one input or the other
may record at a given time but not both.</P>
<P>Usually, inputs on different cards can record at the same time
but two or more inputs on the same card cannot. However, there are cases
where inputs on different cards should not be allowed to record at the
same time, for example, a firewire card and s-video analog card connected
to the same set top cable box.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
|
|   coax +--------------+ firewire    ------------------+
|     .-=|Cable Provider|=------------=| Card 1 input 1 | HDTV
|     |  |HD/Cable STB  |=--.          +-----||||||||||||
|     |  +--------------+   | s-video ------------------+
|     |                     `---------=|        input 2 | Digital
|wall |               coax             | Card 2         |
|=---=^=------------------------------=|        input 3 | Cable
|                                      +-----|||||||||||| 
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Input 1 and input 2 receive content from the same set top box and the
channels can not be tuned independently. Therefore only one of these two
inputs should be used at any given time. The solution is to create an "Input
Group" with <B>mythtv-setup</B> in "Input connections". Including these
two inputs in the same Input Group will tell the scheduler that these are
mutually exclusive and may not record at the same time. Inputs 2 and 3 are
automatically mutually exclusive because they are on the same card so there
is no need to create an Input Group for these inputs.</P>
<P>Cards such as the Hauppauge PVR-500 are able to record as two cards
simultaneously because it has two MPEG-2 encoders and each encoder appears
as a separate device. DVB cards may be allowed to capture content from more
than one channel at a time if the channels are in the same MUX.</P>

<H3>Stations, Channels and Video Sources</H3>

<P>Although we may be accustomed to thinking of a broadcast station and its
channel number as being synonymous, stations and channels are very different
things. A "station" is in a building with wires and employees. A "channel"
is a carrier frequency or digital ID that carries a broadcast stream. The
same TV station may be broadcast over different frequencies in different
cities or by different providers in the same city. The same frequency will
carry different stations in different cities.  In the digital realm of DVB
and ATSC (HDTV), it is even possible for a single frequency to carry
multiple program streams but each of these streams of content are actually
different channels that the receiving devices can 'tune' to independently.</P>
<P>
<UL>
<LI>Station: building</LI>
<LI>Channel: frequency</LI>
</UL>
</P>
<P>In MythTV, a "video source" is a set of channels from a provider, or over
the air, that can be received by an input. The set defines the channels and
the broadcasters primarily associated with each of those channels.  If you
have more than one device or cable from the same provider connected to more
than one card and input, you only need to create one video source in
mythtv-setup then associate that one source with each of these connected
inputs. This will let your MythTV system know that the same channels and
their TV listings are available to be recorded from any of these inputs.</P>
<P>For example. A MythTV system may have two capture cards. Both have a cable
connected to the coaxial connectors. These cables carry the local cable TV
service. In mythtv-setup, the user should create one "Video source" called
"Cable", for example. Under "Input connections", "Cable" should be
associated with each of the two tuner inputs. The scheduler will then know
that any program on one of the channels from the "Cable" source could be
recorded by either card from the card's tuner input.</P>
<P>You need to create a different video source for each provider or service
that has a different set of channels. Each input with a connection to that
service should be associated with the video source for that service so the
system will know which set of channels are available for each of your active
inputs.</P>
<P>Let's say that this user also has one digital cable set top box. The digital
cable service carries channels that are not available over basic cable. The
user would create another source called "Digital". This set top box is
connected to the second card by S-Video so under "Input connections",
"Digital" is associated with the S-Video input of card 2. The system would
then know that programs on channels from the Digital source can only be
recorded from this input. Further, the scheduler understands that it can
only record one show at a time from card 2 so it can assign Cable or Digital
shows to the card but not both at the same time.</P>
<P>Some TV stations may be broadcast over a channel from the Cable source and
also broadcast over a channel from the Digital source. Note that two
channels carrying the same primary station may not have the same TV listings
due to carrying the primary station part time, including local programming
exclusive to one of the channels, the channels may be in different
timezones, etc. Listings information must be associated with each channel
even if two or more channels report that they carry the same station.</P>

<H3>Order of Inputs</H3>

<P>By default the scheduler chooses the first (lowest numbered) input which has
a showing of the scheduled program as it fills the schedule. If a lower
priority show is on at the same time as a higher priority show that has been
assigned to input 1, then input 2 will be used next and so on. Therefore,
configure your best card and input first and next best card and input
second.  There may be differences in the type or brand of capture card,
signal quality from the cable, system resources such as disk space, CPU,
etc. By configuring your best input first, more recordings, and your highest
priority recordings, will use that input.</P>
<P>A common situation is that a newer and better card is added last. For
example, you may initially setup your system with two analog cable cards and
then add a HDTV card. If NBC is on a cable channel and "The Apprentice" is
shown in HDTV on an NBC HD channel, the scheduler would still prefer analog
inputs 1 and 2 over the new HD input 3.</P>
<P>So, if you'd like the scheduler to prefer a new source, the simplest thing
is to run <B>mythtv-setup</B> and "Delete all capture cards" then enter
your cards and inputs in your preferred order. This will not remove your
sources and channels - you want to keep those and only renumber your cards
and inputs. In this example, once the changes have been made and the Master
Backend is restarted, the scheduler would then choose "The Apprentice" in HD
on the new input 1 and only use the analog inputs (now numbered 2 and 3)
when the HDTV input was occupied with another show.</P>

<H3>Matching Callsigns</H3>

<P>If a recording rule is a type that can record from any channel, "The
Apprentice" would match for any channel that shows episodes which may
include CNBC or BRAVO. However, for Single, Timeslot, Weekslot or Channel
rules, "The Apprentice" would only match showings on the selected station as
identified by the "callsign". For example, KVBC is an NBC affiliate on
channel 3. Channel 733 is KVBCDT which is HDTV over cable from the same
station. If a Single record rule was set for "The Apprentice" on KVBC
channel 3, it could not record this showing from KVBCDT on 733. If 733 was
chosen when the rule was saved, channel 3 could not be used to record.</P>
<P>However, the "Channel Editor" in mythtv-setup can be used to change the
Callsign for channel 733 to "KVBC". MythTV would then understand that both
of these channels are from the same broadcast station. Assuming the HDTV
input was input number "1", "The Apprentice" would record on 733. If,
however, this HDTV input already had a higher priority show assigned to it
in that time slot, "The Apprentice" would be assigned to KVBC channel 3 on
input 2.</P>
<P>Having two channels with the same callsign may affect how program
information is shown in mythfrontend. If two sources have the same callsign
and channel number, the program guide and program lists will only show one
instance of the channel number and callsign. If the same callsign is on two
different channel numbers, both will be shown and if two sources have
different callsigns with the same channel number, both of those will be
shown.</P>
<P>Continuing with the example above, the Electronic Program Guide would
include rows for both "3 KVBC" and "733 KVBC". If channel 3 KVBC was also
included in the Digital cable source, the EPG would still include just one
line for "3 KVBC" even though there are two different channels, Cable and
Digital, with this identification. Regardless of how these are displayed and
which "KVBC" channel you select to add a rule to record "The Apprentice",
the scheduler will pick the best channel, source and input to record "The
Apprentice" on "KVBC".</P>

<H3>Using Priorities to Prefer an Input</H3>

<P>The fundamental concept to keep in mind is that the MythTV scheduler will
choose the lowest numbered input available when showings have the same
priority. If there are factors that cause two showings of the same show to
have different priorities then the higher priority showing will be
considered before the showings with lower priority.</P>

<H3>Input Priority</H3>

<P>"Input Connections" in mythtv-setup includes a box to set "Input priority"
which defaults to "0". If a value is set, that amount will be added to the
"total priority" for showings on that input. This can be used to influence
using favored cards or not using less favored cards unless necessary.</P>
<P>Let's say the "The Apprentice" is on at 8:00pm with a priority of 3. "Who
Cares" is -2 and an episode is shown at 8:00pm then repeated at 11:00pm. The
scheduler would assign "The Apprentice" to card 1 and "Who Cares" to card 2
at 8:00pm. If the input priority for the input on card 2 was changed to -1,
"Who Cares" would have a total priority of -2 for showings on card 1 and -3
for showings on card 2. The scheduler would assign "The Apprentice" to card
1 at 8:00pm and "Who Cares" to card 1 at 11:00pm when the better card is
available. If there was another higher priority show at 11pm, the next best
choice for "Who Cares" would be card 2 at 8pm with the priority -3.</P>
<P>Card 1 and 2 have input priority "0":</P>
<P>
<FIGURE>
<EPS FILE="Card1 Pri 0 Card2 Pri 0.eps">
<IMG SRC="Card1 Pri 0 Card2 Pri 0.png">
<CAPTION></CAPTION>
</FIGURE>
</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
 Time  Title     Priority  Card  Status
 8:00  The Apprentice  +3  1     Will Record
 8:00  Who Cares       -2  2     Will Record
11:00  Who Cares       -2  1     Earlier Showing
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Card 2 with input priority "-1":</P>
<P>
<FIGURE>
<EPS FILE="Card1 Pri 0 Card2 Pri -1.eps">
<IMG SRC="Card1 Pri 0 Card2 Pri -1.png">
<CAPTION></CAPTION>
</FIGURE>
</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
 Time  Title     Priority  Card  Status
 8:00  The Apprentice  +3  1     Will Record
 8:00  Who Cares       -3  2     Later Showing
11:00  Who Cares       -2  1     Will Record
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Card 2 at "-1" but higher priority shows at both 8 P.M. and 11 P.M.:</P>
<P>
<FIGURE>
<EPS FILE="Card1 Pri 0 Card2 Pri -1-TDS.eps">
<IMG SRC="Card1 Pri 0 Card2 Pri -1-TDS.png">
<CAPTION></CAPTION>
</FIGURE>
</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
 Time  Title     Priority  Card  Status
 8:00  The Apprentice  +3  1     Will Record
 8:00  Who Cares       -3  2     Will Record
11:00  The Daily Show  +1  1     Will Record
11:00  Who Cares       -3  2     Earlier Showing
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Note the two different effects, each of which may be what you desire
depending on circumstance. If input priorities are equal, shows will record
at the earliest time if any input is available. If input priorities differ,
shows may be postponed to a later time in order to record on the best input.</P>

<H3>Channel Priority</H3>

<P>Priority can be added for individual channels (remember, frequencies from a
video source, not stations). This can be used to tell the system that you
generally prefer the content of the station on a channel over the formats of
other stations. You may want to raise the priority for ESPN, SciFi, Comedy
Central or lower the priority for CSPAN, CourtTV, etc. If the same station
is on two different channels, you can use channel priority to have the same
effect for these channels as input priority would have for whole inputs.</P>
<P>For example, say CNN is on analog channel 20 and there is an HD CNN on 750.
You may not want to tie up the HD input for news originating in standard
definition. Under TV Settings->Recording Priorities->Channel Priorities you
could set channel 750 to -1. The scheduler would then prefer to record CNN
shows on any analog channel 20 before considering using 750 only when there
are no analog inputs available.</P>

<H3>Preferred Input</H3>

<P>For an even finer grain of control, there is a per rule option to specify
which input should be preferred for showings that match the rule. By
default, this adds +2 to the priority for showings on the specified input.</P>
<P>For illustration, let's say there will be a Space Shuttle launch on CNN that
will be broadcast in high definition. Adding a rule to record the launch
with priority "0" should default to channel 20 on input 2. Channel 750 would
have this at -1 due to the channel priority set in the previous example. If
on the recording options page for this rule, the "Scheduling Options" had
the input set to prefer the HD input on card 1, then the showing on channel
750 for this input would be increased in value by +2 for a total of +1 and
would be the best choice for this launch coverage.  While this one rule
would prefer the HD input with channel 750, all other rules that match shows
on CNN would still prefer channel 20.</P>
<P>Note that this will not work properly if the preferred input priority does
not out weigh differences in input and channel priorities.  The value of the
priority boost when this option is chosen defaults to +2 but can be modified
in TV Settings->Recording Priorities->Set Recording Priorities.</P>

<H3>HDTV Priority</H3>

<P>In the preceeding fictious example, the Space Shuttle launch is broadcast in
high definition and a preferred input is selected to give preference to the
HD input. However, TV listings from zap2it.com through the DataDirect
service may allow this to work without having to use this per rule option.</P>
<P>In Settings->Recording Priorities->Set Recording Priorities there is an
option for "HDTV Recording Priority". This value will be added automatically
if the listings for the show have the "hdtv" flag set. DataDirect will set
this flag for shows known to be broadcast in HDTV on HD channels. However,
the flag is not set for standard definition channels. This is another
example of the listings being different for the same station on a different
channel. If the HDTV priority is set to "+2", the shuttle launch would
automatically have a total priority of +1 so that channel 750 would be
preferred over channel 20 for this HDTV broadcast.</P>
<P>Channel "750 CNN" at priority "-1" and HDTV broadcast priority at "+2":</P>
<P>
<FIGURE>
<EPS FILE="Card1 HDTV Card2 Cable.eps">
<IMG SRC="Card1 HDTV Card2 Cable.png">
<CAPTION></CAPTION>
</FIGURE>
</P>

<H3><A NAME="Custom Priority"></A> Custom Priority </H3>

<P>
<FIGURE>
<EPS FILE="add.eps">
<IMG SRC="add.png">
<CAPTION>New for MythTV 0.21</CAPTION>
</FIGURE>
</P>
<P>While Input, Channel, and HDTV Priority can be used for indicating a
preference for certain programs and inputs, there may be circumstances that
cannot be resolved easily with these standard features. MythTV version 0.21
includes a feature for "power priority". The Custom Priority editor in
mythfrontend's "TV Settings" screen is similar to Custom Record, however,
Custom Priority allows you to create specialized power priority factors to
influence scheduling decisions.</P>
<P>For example, the 'program.closecaptioned' flag can be used in a
similar way as the 'program.hdtv' flag.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Priority Rule Name: Closed Captioned priority
Priority Value: 2
program.closecaptioned > 0
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>This will raise the priority of shows marked with "CC" over those that are
not by applying the "Priority Value" whenever the SQL fragment evaluates to
true. If the expression evaluates to false for a showing, the "Priority
Value" is not applied.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Priority Rule Name: Priority when shown once
Priority Value: 1
program.first > 0 AND program.last > 0
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The "first" and "last" flags for an episode will only be set for the
same showing when there is only one showing of that episode in the
current TV listings. This rule would raise the priority in these cases
so that these shows would have an advantage to record in their only
available time slot.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Priority Rule Name: Input 1 signal quality
Priority Value: -1
cardinput.cardinputid = 1 AND
channel.channum IN (3, 5, 39, 66)
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>A common issue with two or more analog capture cards is that one of
the cards may have more interference on some channels than the same
channels on other cards. This example gives a disadvantage to the
channels in this list but only for the first input. Therefore, a show
on channel 39 would choose input 2 or 3 if possible but for channels
not in this list, input 1 is still the first choice.</P>
<P>The Custom Priority editor includes many example fragments and complete
examples that can be used or you can create your own to suit your needs.</P>

<HR>
<A HREF="mythtv-HOWTO-13.html">Next</A>
<A HREF="mythtv-HOWTO-11.html">Previous</A>
<A HREF="mythtv-HOWTO.html#toc12">Contents</A>
</BODY>
</HTML>