Recording Status
| Author | Phil Brady |
| Description | Manipulating and examining the state of recordings with the api interface. |
| Supports |
Contents
Aims
This wiki has been written to clarify the state of recordings as returned by api calls.
It was written after seeing the discussion which took place in March 2023 in the developers' email list and can be seen here: https://lists.archive.carbon60.com/mythtv/dev/643622
This, and other v34 changes, resulted in changes to the API interface which may affect API applications.
Values given here are those obtained by firing a number of API calls to a backend running MythTV Version v34.0~master.202306020720.ed409bfc02~ubuntu22.04.1 and by discussion with developers.
Which Family?
There are two families of api calls which return an item describing the status of a recording.
The first family relates to recording rules as used by calls such as Dvr/GetRecordSchedule, Dvr/AddRecordSchedule and Dvr/UpdateRecordSchedule. They use parameters 'Type' and 'Filter'.
The second family includes calls such as Guide/GetProgramGuide, Guide/GetProgramDetails, Guide/ GetProgramList and Dvr/GetUpcomingList. These return parameters 'Status' and, in later releases 'StatusName'.
Recording Rules
These calls use 'Type' and 'Filter' parameters. See https://www.mythtv.org/wiki/DVR_Service#GetRecordScheduleList
Essentially, to record a program, issue a GetRecordSchedule, alter 'Type' to (say) 'Record One', copy 'CallSign' to 'Station', alter Filter if necessary and post an AddRecordSchedule or an UpdateRecordSchedule.
Values for 'Type' can be obtained from api calls /Dvr/RecTypeToString?RecType=value and /Dvr/RecTypeToDescription?RecType=value and from source code https://github.com/MythTV/mythtv/blob/eea10424c0bbe65133120ff2899d20d8068e07f1/mythtv/libs/libmythbase/recordingtypes.cpp#L101
String Description Not Recording = Do not record this programme Single Record = Record only this showing Record Daily = Record one showing every day Record All = Record all showings Record Weekly = Record one showing every week Record One = Record only one showing Override Recording = Record this showing with override options If you override a recording specify new filters. To stop a single recording in a series, use 'Not Recording'.
The 'Filter' field allows selection by criteria such as 'this channel' and is described here: https://forum.mythtv.org/viewtopic.php?f=33&t=3175
Status Family
There are four pieces of information which will be encountered when using this family. They are Status, StatusName, String and Description.
eg: Status = -1 (but before v34 March 2023, xml will return 'WillRecord') StatusName = WillRecord String = Will Record Description = This showing will be recorded
The String and Description can be obtained with /Dvr/RecStatusToString?RecStatus=value and /Dvr/RecStatusToDescription?RecStatus=value and are listed in the appendix below.
Note that StatusName is the same as String but with any spaces removed.
V34 changes
Port Changes
Prior to v32, all backend API calls were to port 6544.
In v32, a revised API interface was introduced, now called API v2, on backend port 6744. It was intended that in time this interface would replace API v1 and be presented on port 6544.
With v34, no enhancements or bug fixes were applied to API v1 code.
It is understood that on release of v34, port 6544 will present the API v2. Port 6744 will still be available carrying v2, and those wishing to test with the old v1 interface will have to use port 6550.
In time, ports 6744 and 6550 will be removed.
Format of tags
The format of xml tags changed with API v2. Previously one would have had for example <Program>....</Program> but this is now replaced by a longer tag: <Program version="1.12">...</Program>.
If you use a simple method of extracting values such as a regex then you might need to change your code.
Numeric Status
There was discussion of a bug in March 2023 whereby json calls to the STATUS family return a numeric value (eg -1) for 'Status' but xml calls return StatusName values (eg WillRecord). See: https://lists.archive.carbon60.com/mythtv/dev/643622
The wiki/api pages suggest that back in 2011 xml calls returned numeric values for Status and the wiki has not been changed since but by November 2019 it was reported that they had changed to text (eg 'WillRecord' not -1). See: https://forum.mythtv.org/viewtopic.php?f=33&t=3422
A fix has been applied to port 6744 which involves:
- The Status field for xml calls is changed back to be numeric (eg WillRecord reverts to -1).
- An extra field 'StatusName' is added to the responses to both xml and json calls.
- The /Dvr/RecStatusToString?RecStatus= and /Dvr/RecStatusToDescription?RecStatus= calls are enhanced to accept both
StatusName and String as input in addition to the numeric values.
The fix should also be embedded in port 6544 before v34 is released.
Change to Guide/GetProgramList
Versions of Mythtv prior to v34 would return spurious values of Status for programs which were not being recorded.
In v34 the whole <Recording> ... </Recording> section will be blank for such programs.
Applications reliant on the presence of (say) <Status> will need change.
The change may not be limited to GetProgramList.
Application Changes
Calls using the json interface may need change to reflect the change to GetProgramList.
If using the xml interface then any application relying on a 'Status' value will need change to preserve compatibility.
The simplest approach after issuing a call such as Dvr/GetUpcomingList is to check the value of Status.
If 'Status' is missing then assume a status of Won'tRecord.
If it is numeric (it may be negative) then StatusName will also be present and should be used instead of Status.
A call to /Dvr/RecStatusToString will not be helpful in resolving this - non numeric values of status will only be returned by backend versions prior to the RecStatusToString enhancement.
Appendix
This list was generated with MythTV Version v34.0~master.202306020720.ed409bfc02~ubuntu22.04.1 and calls to backend:6744/Dvr/RecStatusToString?RecStatus= and backend:6744/Dvr/RecStatusToDescription?RecStatus=.
RecStatus String description
-16 => Unknown = The status of this showing is unknown.
-15 => Pending = This showing is about to record.
-14 => Failing = The showing is failing to record because of errors.
-13 => Unknown = The status of this showing is unknown.
-12 => Unknown = The status of this showing is unknown.
-11 => Missed = This showing was not recorded because the master backend was not running.
-10 => Tuning = The showing is being tuned.
-9 => Recorder Failed = This showing was not recorded because the recorder failed.
-8 => Tuner Busy = This showing was not recorded because the recorder was already in use.
-7 => Low Disk Space = This showing was not recorded because there wasn't enough disk space.
-6 => Manual Cancel = This showing was not recorded because it was manually cancelled.
-5 => Missed = This showing was not recorded because the master backend was not running.
-4 => Aborted = This showing was recorded but was aborted before completion.
-3 => Recorded = This showing was recorded.
-2 => Recording = This showing is being recorded.
-1 => Will Record = This showing will be recorded.
0 => Not Recording = This showing is not scheduled to record
1 => Don't Record = This showing was not recorded because it was manually set to not record.
2 => Previously Recorded = This showing was not recorded because this episode was previously recorded
according to the duplicate policy chosen for this title.
3 => Currently Recorded = This showing was not recorded because this episode was previously recorded
and is still available in the list of recordings.
4 => Earlier Showing = This showing was not recorded because this episode will be recorded at an
earlier time instead.
5 => Max Recordings = This showing was not recorded because too many recordings of this programme
have already been recorded.
6 => Not Listed = This showing was not recorded because this rule does not match any showings
in the current programme listings.
7 => Conflicting = This showing was not recorded because another programme with a higher
priority will be recorded.
8 => Later Showing = This showing was not recorded because this episode will be recorded at a
later time instead.
9 => Repeat = This showing was not recorded because this episode is a repeat.
10 => Inactive = This showing was not recorded because this recording rule is inactive.
11 => Never Record = This showing was not recorded because it was marked to never be recorded.
12 => Recorder Off-Line = This showing was not recorded because the required recorder is off-line.
13 => Unknown = This showing was not recorded.
14 => Unknown = This showing was not recorded.
15 => Unknown = This showing was not recorded.
16 => Unknown = This showing was not recorded.
Aborted => Aborted = This showing was recorded but was aborted before completion.
Conflicting => Not Recording = This showing is not scheduled to record
CurrentlyRecorded => Not Recording = This showing is not scheduled to record
Don'tRecord => Not Recording = This showing is not scheduled to record
EarlierShowing => Earlier Showing = This showing was not recorded because this episode will be recorded at an
earlier time instead.
Failing => Failing = The showing is failing to record because of errors.
Inactive => Inactive = This showing was not recorded because this recording rule is inactive.
LaterShowing => Later Showing = This showing was not recorded because this episode will be recorded at a
later time instead.
LowDiskSpace => Low Disk Space = This showing was not recorded because there wasn't enough disk space.
ManualCancel => Not Recording = This showing is not scheduled to record
MaxRecordings => Not Recording = This showing is not scheduled to record
Missed => Missed = This showing was not recorded because the master backend was not running.
NeverRecord => Never Record = This showing was not recorded because it was marked to never be recorded.
NotListed => Not Listed = This showing was not recorded because this rule does not match any showings
in the current programme listings.
NotRecording => Not Recording = This showing is not scheduled to record
Pending => Pending = This showing is about to record.
PreviouslyRecorded => Not Recording = This showing is not scheduled to record
Recorded => Recorded = This showing was recorded.
RecorderFailed => Not Recording = This showing is not scheduled to record
RecorderOff-Line => Not Recording = This showing is not scheduled to record
Recording => Recording = This showing is being recorded.
Repeat => Repeat = This showing was not recorded because this episode is a repeat.
TunerBusy => Tuner Busy = This showing was not recorded because the recorder was already in use.
Tuning => Tuning = The showing is being tuned.
Unknown => Not Recording = This showing is not scheduled to record
WillRecord => Will Record = This showing will be recorded.
This may not be an exhaustive list and you may experience a StatusName of CurrentRecording instead of CurrentlyRecorded.
Acknowledgement
Thanks to Peter Bennet for his patience in answering my many queries.
