======DVR Recording Rules======
<btn type="success" size="xs" icon="fa fa-chevron-left">[[:DVR API|Back to all DVR API topics]]</btn>

<WRAP center info>
This is a mirror of the documentation from: https://github.com/Silicondust/documentation/wiki/DVR-Recording-Rules
</WRAP>


A Series rule will record every unique episode that matches the given criteria within a TV series. The rule does not expire. Only one Series rule can exist per TV series.

A Movie rule will record the first showing of the movie that matches the given criteria. The rule will automatically expire after the movie has been recorded. Only one Movie rule can exist per movie.

A DateTimeOnly-ChannelOnly rule will record a single airing of the specified TV series or movie at the specified date and time on the specified channel. The rule will automatically expire once the time has passed even if it did not result in a recording. Multiple unique DateTimeOnly-ChannelOnly rules can exist for the same series.

====API URL====
<WRAP indent>

<code>https://api.hdhomerun.com/api/recording_rules</code>

</WRAP>
====List recording rules====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |

Returns: Details all matching recording rules, or "null" if no matching rules exist. Results are ordered DateTimeOnly first, then by priority highest first.

</WRAP>
====Add a series recording rule====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |
| Cmd | string | "add" |
| SeriesID | string | SeriesID identifying the series or movie to record. |
| ChannelOnly | string | Optional. Pipe separated list of virtual channel numbers - record only on the specified channels. |
| TeamOnly | string | Optional. Pipe separated list of team names - record only if one of the specified teams is playing. |
| RecentOnly | bool | Optional. Record only recent episodes (default 0). |
| AfterOriginalAirdateOnly | int64 | Optional. Record only if the original airdate is the same or after (UTC unixtime). |
| StartPadding | uint | Optional. Start recording early (seconds, default 30s, max 1h). |
| EndPadding | uint | Optional. Continue recording past end (seconds, default 30s, max 3h). |

Returns: Details of all recording rules.

</WRAP>
====Add a DateTimeOnly-ChannelOnly recording rule====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |
| Cmd | string | "add" |
| SeriesID | string | SeriesID identifying the series or movie to record. |
| DateTimeOnly | int64 | Record only the airing that starts at this time (UTC unixtime). |
| ChannelOnly | string | Record only the airing on this virtual channel number. |
| StartPadding | uint | Optional. Start recording early (seconds, default 30s, max 1h). |
| EndPadding | uint | Optional. Continue recording past end (seconds, default 30s, max 3h). |

Both DateTimeOnly and ChannelOnly are required. ChannelOnly must be a single channel number.

Returns: Details of all recording rules

</WRAP>
====Modify a series recording rule====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |
| Cmd | string | "change" |
| RecordingRuleID | string | Optional/Required. ID identifying the rule to modify. |
| SeriesID | string | Optional/Required. SeriesID identifying the series or movie to modify. |
| ChannelOnly | string | Optional. Pipe separated list of virtual channel numbers - record only on the specified channels. |
| TeamOnly | string | Optional. Pipe separated list of team names - record only if one of the specified teams is playing. |
| RecentOnly | bool | Optional. Record only recent episodes (default 0). |
| AfterOriginalAirdateOnly | int64 | Optional. Record only if the original airdate is the same or after (UTC unixtime). |
| StartPadding | uint | Optional. Start recording early (seconds, default 30s, max 1h). |
| EndPadding | uint | Optional. Continue recording past end (seconds, default 30s, max 3h). |

The RecordingRuleID must be specified or the SeriesID must be specified. The request will be rejected if both are specified.

Returns: Details of all recording rules.
</WRAP>
====Modify a DateTimeOnly-ChannelOnly recording rule====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |
| Cmd | string | "change" |
| RecordingRuleID | string | Optional/Required. ID identifying the rule to modify. |
| SeriesID | string | Optional/Required. SeriesID identifying the rule to modify. |
| DateTimeOnly | int64 | Optional/Required. Unix timestamp identifying the rule to modify. |
| ChannelOnly | string | Optional/Required. Virtual channel number identifying the rule to modify. |
| StartPadding | uint | Optional. Start recording early (seconds, default 30s, max 1h). |
| EndPadding | uint | Optional. Continue recording past end (seconds, default 30s, max 3h). |

The RecordingRuleID must be specified or the SeriesID, DateTimeOnly, and ChannelOnly must be specified.

Returns: Details of all recording rules.

</WRAP>
====Change the priority of a recording rule====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |
| Cmd | string | "change" |
| RecordingRuleID | string | ID identifying the rule to modify. |
| AfterRecordingRuleID | string | The new priority of the rule by specifying which rule it should be directly after, or 0 to make the highest priority. |

Priority applies to Series and Movie rules only. DateTimeOnly-ChannelOnly rules are always highest priority.

Returns: Details of all recording rules.

</WRAP>
====Delete a series recording rule====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |
| Cmd | string | "delete" |
| RecordingRuleID | string | Optional/Required. ID identifying the rule to delete. |
| SeriesID | string | Optional/Required. SeriesID identifying the series or movie to delete. |

The RecordingRuleID must be specified or the SeriesID must be specified. The request will be rejected if both are specified.

Returns: Details of all recording rules.

</WRAP>
====Delete a DateTimeOnly-ChannelOnly recording rule====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. |
| Cmd | string | "delete" |
| RecordingRuleID | string | Optional/Required. ID identifying the rule to delete. |
| SeriesID | string | Optional/Required. SeriesID identifying the rule to delete. |
| DateTimeOnly | int64 | Optional/Required. Unix timestamp identifying the rule to delete. |
| ChannelOnly | string | Optional/Required. Virtual channel number identifying the rule to delete. |

The RecordingRuleID must be specified or the SeriesID, DateTimeOnly, and ChannelOnly must be specified.

Returns: Details of all recording rules.

</WRAP>
====Result format====
<WRAP indent>
<code>
[
    {
        "RecordingRuleID": "403922",
        "SeriesID": "11579711",
        "Title": "Skyfall",
        "Synopsis": "With MI6 under attack, James Bond comes to M's rescue when her daunting past comes back to haunt her, forcing him to seek revenge and take down whoever gets in his way in an effort to find the dangerous assassin before its too late. (3.5/4.0)",
        "ImageURL": "http://my.hdhomerun.com/fyimediaservices/v_3_3_6_1/Program.svc/96/1579711/Primary",
        "ChannelOnly": "2.1|702",
        "AfterOriginalAirdateOnly": 1351209600,
        "TeamOnly": "England|Wales",
        "DateTimeOnly": 1455212160,
        "Priority": 1,
        "StartPadding": 30,
        "EndPadding": 30
    },
    {
        ...
    }
]
</code>

</WRAP>
====Additional Details====
<WRAP indent>

Specifying AfterOriginalAirdateOnly will restrict recordings to first-airings and shows with an original airdate greater than or equal to the given date. A first-airing will match regardless of the original airdate - this ensures shows without per-episode information are recorded. Repeats without a known original airdate are not recorded.

</WRAP>
==== History ====
<WRAP indent>

  * 20201024:
    * API changes.

  * 20160318:
    * Add TeamOnly rules.
    * Expand delete command.

  * 20160218:
    * Add command will update an existing rule if a collision occurs.
    * The OriginalAirdate associated with the series no longer reported in the recording rule results.
    * Results include all matching rules if a SeriesID is specified.
</WRAP>

Copyright © 2016-2020 Silicondust USA Inc. <www.silicondust.com>.