[ksooo]

Hi PVR add-on developers,

Just wanted to give you all a heads up for a bigger PVR API change aiming to finally officially support series recordings in Kodi:

https://github.com/xbmc/xbmc/pull/7079

This will bring official series support to Kodi PVR, including a simple and consistent user interface.

I consider the API final, but if I forgot something important, this is the right time to let me know.

With this PR all the hand crafted series recording support (including own dialogs and stuff) that might be built in into your add-on should become obsolete.

Is planned to merge this PR early after isengard branch has been created.

I want to ask you all for preparing the required changes in the add-ons you maintain. It is definitely more than just a one liner, but it's worth the effort, I think.

- Kai.

[metaron]

I believe we all want the PVR API changes to be merged as soon as possible (i.e. once Isenguard is branched).
Tweaks to Kodi's PVR core which don't affect the API can be worked on later. Skin issues can be worked on later.
Changes to the detail for particular Addons that don't require API changes can be worked on later.

The immediate objective is therefore to freeze an API which supports the desired new features,
with sufficient flexibility so addon maintainers can start implementing without needing further API changes.

To be sure PR7079 is ready, I suggest we ask the following questions:

Q: What are the 'legacy' features we want to keep & why?
A1: Standard 'Timer' based recordings (this channel, at this time, for this long) - All backends do this. Backwards compatabiltiy.
A2: Repeating 'Timer' based recordings (this channel, at this time, for this long, on these days) - Fallback. Doesn't need a good EPG.
A3: Timeshift

Q: What are the desired new features & why?
A1: EPG Based Once recording (Find and record 'the optimum' upcoming showing of the selected episode)
A2: EPG Based Series recording (Find and record all distinct episodes of this show, using 'optimum' settings)
A3: EPG Based 'Advanced Search' recording (e.g. Find and record all films with 'Carry Grant' in them or 'Terminator' in the title)
A4: A means to adjust 'back end specific' settings (avoiding attribute mapping issues with different backends)

Q: What API changes do we need to support these new desired features?
A1: A means to determine if a PVR client supports the new timer types
A2: A means to instruct a PVR client to add a new timer of the requested type
A3: A means to know when EPG timers will actually record, including conflicts and metadata.
A4: A means to edit both 'legacy' and EPG based timers after creation
A5: A means to edit 'back end specific' timer settings after timer creation

This assumes the following responsibilities:

Kodi PVR core:
KK1: Presentation of Timers and associated metadata.
KK2: Requesting New Timers. Deleting Timers. Activating/Deactivating (manging conflicts).
KK3: Editing Timers.
KK4: Definition of 'essential timer settings' and presentable timer metadata.
KK5: Definition of supportable 'Timer Types'?

PVR Clients:
PC1: Translation of New & Delete Timer requests into 'backend speak' for each supported 'timer type'.
PC2: Translation of upcoming recordings and associated timers into 'Kodi speak'.
PC3: Translation of 'essential timer settings' between 'kodi speak' and 'backend speak'.
PC4: Formatting back-end specific settings / options for kodi-core to present to the user for editing
PC5: Translating 'backend speak' timer metadata into 'kodi speak'.

Back-End:
BE1: Converting timers into upcoming recordings using the settings requested by the PVR client.
BE2: Informing the PVR client of upcoming recordings and timer metadata.

To give some context to these comments, I'm a long term mythtv user who just played with Ksooo's latest tvheadend prototype and 'skimmed' the code. I plan to look at specifics in detail in the next few days and to make separate comments, but am sure there are others with a much better grip on the proposed API (and CPP in general) than I have. Given this and the 'urgency' it is probably better to ask the question and see what others think.

My questions are:

• Do others agree with my stated objectives for the API?
  
• Are there any 'missing' API features critical enough delay merge?
  
• Are there any bits of the API which could be simplified/made more flexible?
  

I can only apologize ksooo, I would much rather have posted this at 13:45 on 2015-05-15.

[scarecrow420]

I've been keeping an eye on it all and participating in the github discussion. From our perspective (pvr.wmc) this is fantastic and seems to cover all the bases. We are ready and willing to build our side of the changes once merged, or perhaps starting now if the changes are getting to the finalised state

[ksooo]

I will supply PRs for all PVR add-ons the very next days. These PRs will ensure compatibility and minimalistic support for API 1.9.7. To leverage the new features possible due to the new API each add-on must be adapted by the respective owners, though.

Short: if the maintainer does nothing, almost all stays the same for the add-on wrt functionality, and (hopefully) nothing gets broken.

[metaron]

When I schedule a new recording (at present using mythweb), I usually do the following:

1. Select an EPG guide entry or search for an upcoming title name
   
2. Pick the type of recording I want (i.e. EPG Once Any Channel or EPG All Any Channel)
   
3. Adjust if I want this recording to auto-expire or not when disk space runs out (i.e. keep the 'box set', or delete old soaps)
   
4. Select a recording group (drop down list of back-end pre-configured groups which selects a storage 'folder' for me - Films/Nature/SiFi/MurderMystery)
   
5. Set how many back episodes I want to keep (for soaps)
   

One of my main gripes with the (helix) PVR code at present is that it doesn't give me a list of 'timer settings' for adjustment which covers these use cases.

If I understand correctly, while this new API will allow the first step and 1/2 of the second, unless I misunderstand, I will still have to find the recording rule in mythtv later and tweak the 'autoexpire' 'recording group' and 'no of recordings to keep' settings and if I want my 'record once' rule to choose to record on ITV1, IVT1+1 or ITV HD automatically, I will have to turn off the 'this channel only' flag as well, which may well confuse the pvr.mythtv client and kodi when it tries to classify the timer type for display later.

While the API makes it simple for a PVR client to decide if it wants to support a pre-defined feature like 'folder names' or 'storage priority', adding extra options like 'recording group' or 'no of recordings to keep' won't be possible without changing the API, which will require the PVR core to change and then possibly all the addons as well (i.e. a long release cycle with a lot of interested parties).

My suggestion is that other than a few essential core timer variables, which should be kept to a minimum, most of the settings for advanced EPG timers should be presented to the user by the PVR client using a callback mechanism.
e.g. bSettingsChanged = PresentExtraTimerSettingsForAdjustment (PVR_CLIENT iClient, PVR_TIMER iTimer);

If I understand correctly the timer settings dialog uses a 'generic' dialog which is simply populated with a list of 'settings' to change.
If the responsibility for choosing these settings falls to the PVR client, each addon maintainer is free to choose those settings which best map to the selected backend features which the user base wants access to. They could even make this set of displayed settings 'configurable' on the addon settings pages.

I can see that the timer options which work well for tvheadend don't work well for mythtv (at least for my use cases). I suspect that when you look at the other supported PVR clients in detail, there will be other 'must have' settings which don't map well to those already 'pre-defined'.

If this API is added now, when each addon maintainer implements the new EPG based types, they can implement the callback. The existing settings mechanism can be used until an addon says it supports the 'settings callback'. When it does, that gets used instead.

[ksooo]

Your suggestions do not conflict with what is planned for J******, thus imo can be added in a next step. The good thing about open-source is that everybody is invited to contribute the respective code.

[metaron]

Sounds like something worth the effort to me :-). Github login here we come...

[ksooo]

Cool. Go ahead. I will happy to assist.

[metaron]

@ksooo
I've had closer look at your code and what would be required to implement my stated objectives (above) in the mythtv client.
I've come to the conclusion there are only two things missing.

• Recording Group (effectively a pre-defined list of 'Folders' rather than a free text field)
  
• Recording Lifetime (number of recordings to keep rather than a days based lifetime)
  

Everything else I would want to change using a remote is already there in the API.

The options seem to be:

1. Replacement dialog (as I suggested before) - lots of duplicated effort required by each addon maintainer.
   
2. A menu hook to add extra options - flexible, minimum addon maintainer work, but lots of complexity to set up
   
3. Slightly extending the current options to cater for the mythtv philosophy.
   

I've decided the quickest, easiest (and probably best) option is to have a go at 3.
I plan to prototyping the following changes for your consideration:

Folder List:
New ''PVR_TIMER_TYPE_SUPPORTS_RECORDING_FOLDER_LIST" (with a filler function provided by the addon)

This would be a simple alternative to freetext folder entry. I would prefer to set up a list of folders in advance (in the addon settings pages or via the backend) as I don't have a keyboard attached to my TV.

Lifetime:
This is a bit more complex. I note that @ryangribble commented regarding pvr.wmc (https://github.com/xbmc/xbmc/pull/7079):

And for lifetime we can do keep until watched/keep until space needed /keep recent etc

Seems there are several different philosophies out there.

• TVheadend - Number of days
  
• Mythtv - Keep Forever / Number of Recordings (most recently shown) / Number of Recordings (first shown) / Until space needed
  
• WMC - Keep Recent (days/number of recordings?) / Until Watched / Until space needed
  

I would propose a list which like the 'Any Time' toggle controls the display while allowing the user to select from supported options. A lifetime in days or number of recordings is then presented as a spinner below where appropriate.

New "PVR_TIMER_TYPE_SUPPORTS_KEEP_FOREVER"
New "PVR_TIMER_TYPE_SUPPORTS_KEEP_MOST_RECENT" (new number of recordings spinner / reuse 'days' spinner?)
New "PVR_TIMER_TYPE_SUPPORTS_KEEP_FIRST_SHOWN" (new number of recordings spinner / reuse 'days' spinner?)
New "PVR_TIMER_TYPE_SUPPORTS_KEEP_UNTIL_WATCHED"
New "PVR_TIMER_TYPE_SUPPORTS_KEEP_UNTIL_DISK_FULL"
Existing "PVR_TIMER_TYPE_SUPPORTS_LIFETIME" (existing 'days' spinner) - Maybe rename this "PVR_TIMER_TYPE_SUPPORTS_KEEP_LIFETIME"?

Are there any other recording expiration philosophies out there which ought to be catered for?

I accept this has almost certainly missed the boat for this PR (imho this is part of the 20% in the 80-20 rule), but maybe it will make a later revision before Jxxxxx hits the streets if I can get it working quickly enough...

[ksooo]

Regarding lifetime: API already allows to completely redefine values and semantics. from my point of view we already have all that is needed. => https://github.com/xbmc/xbmc/blob/0aab86...pes.h#L331

[ksooo]

Regarding recording folder list: your suggestion fita nicely in the existing API concept. We would need to define a new timer type attribute plus add API support for letting the add-on define own values for this attribute (exactly like we already did for lifetime), finally implement that attribute in the timer settings dialog. Then, the add-on can fill the respective data. That's it. Nothing really complicated. ;-)

If I find the time I will add this to the existing PR, but cannot promise anything.

[metaron]

Regarding lifetime: API already allows to completely redefine values and semantics. from my point of view we already have all that is needed. => https://github.com/xbmc/xbmc/blob/0aab86...pes.h#L331

I don't see how yet, but I'll take your word for it. This looked like the more difficult one to me anyhow

Regarding recording folder list: your suggestion fita nicely in the existing API concept. We would need to define a new timer type attribute plus add API support for letting the add-on define own values for this attribute (exactly like we already did for lifetime), finally implement that attribute in the timer settings dialog. Then, the add-on can fill the respective data. That's it. Nothing really complicated. ;-)

If I find the time I will add this to the existing PR, but cannot promise anything.

I'll have a go and send you a PR based on the 'pvr-series-recordings' branch in the next couple of days. From an API perspective it looks like a copy of the "prevent duplicate episodes" method with a different name (or at least a pick and mix from the other methods), so I should be able to cope

[ksooo]

Okay, go ahead.

[metaron]

@ksooo and other interested parties, the promised pull request can be found at: https://github.com/ksooo/xbmc/pull/2
I also worked out how Lifetime could be tweaked to allow non-integer settings - so no more doubts there!

On closer examination the API looks easily extensible and flexible enough to cope with almost anything the clients can throw at it. Excellent work!

The only minor comment I have is that the order of the settings seems to be fixed in the 'Timer Settings' dialog, but maybe that's for the best. It appears any 'lists' or 'skips' need to be pushed onto TimerTypes in the order defined in GUIDialogPVRTimerSettings.cpp.

Unless this is 'skinnable' in some way, it looks as if, should someone decide during Jxxxx development that 'Recording Group' should come before 'Lifetime' for example, clients would have to be re-written to change the order in which they push their lists.

Personally I think I could live with this limitation, but there may be others who disagree.

[ksooo]

The order of the timer attributes is hard coded in the timer settings dialog and cannot be changed by the add-on in any way.