Kodi Community Forum
Planned API changes for Series Recordings - Printable Version

+- Kodi Community Forum (https://forum.kodi.tv)
+-- Forum: Development (https://forum.kodi.tv/forumdisplay.php?fid=32)
+--- Forum: Add-ons (https://forum.kodi.tv/forumdisplay.php?fid=26)
+---- Forum: PVR (https://forum.kodi.tv/forumdisplay.php?fid=136)
+---- Thread: Planned API changes for Series Recordings (/showthread.php?tid=227026)

Pages: 1 2 3 4 5 6 7 8 9 10 11 12

RE: Planned API changes for Series Recordings - metaron - 2015-07-24

Sounds to me like a good idea. It would need:
  • a PVR_TIMER_TYPE_SUPPORTS_MAX_RECORDINGS flag in PVR_TIMER_TYPE
  • an iMaxRecordings variable in PVR_TIMER
  • a new spinner "Maximum Recordings" appearing directly below Lifetime in the TimerSettings dialog
  • conditional visibility for "Maximum Recordings"
  • The following Spinner options with default setting 'Unlimited':
    • Unlimited
    • 1
    • ...
    • 100
My feeling is the list doesn't need to be client configurable. Would a list like this work for WMC?
(An unlisted value of iMaxRecordings could be added to the spinner on the fly as was recently done for dates)

It could be made partially configurable (with a range specified by the client), or for API consistency fully configurable but I know there was some concern about list memory usage. Personally I think this is overkill. @ksooo, @janbar, @opdenkamp, @jalle19 what do you think?

Another problem I can see is that this setting might only be valid for some cases of 'Lifetime'.
For Mythtv, in conjunction with a list like this, Lifetime could be changed to:
  • Recordings never expire
  • Allow recordings to expire
  • Record new and expire old
And they would all be valid (well not for unlimited), but does this also work for wmc?

There are already cases for mythtv where 'AnyChannel' isn't valid, but still appears in the channel list, so maybe a precedent has already been set regarding invalid combinations.

RE: Planned API changes for Series Recordings - metaron - 2015-07-24

I've pushed some additional changes (see https://github.com/xbmc/xbmc/compare/master...metaron-uk:apiChanges)
  • PVR_TIMER and PVR_RECORDING
    - iYear (so the IMBD scraper knows which movie remake this is / for consistent presentation)
  • EPG_TAG
    - strRecordingId (unique ID of this recording on the client, if available)
    (@opdenkamp said he would like to be able to select recorded shows to watch directly from the guide some day. If this value is set a new EPG icon/menu option could appear to allow playback to be started from the EPG...)
  • the proposal for max recordings in the previous post.
All these changes will obviously need changes to PVR core to make them work. The EPG one might even need an EPG database change.

My thinking is use one PR to corale the API changes and separate PRs for each of the individual associated PVR core changes. That way separate people can work on/review the associated PVR core changes. Once the changes are mature enough, the API PR and associated change PRs can be merged at the same time.

If the API is considered mature enough it could even be rolled first with the supporting code catching up later.
Does that seem a sensible/acceptable approach? It should help minimize the number of API bumps.

Planned API changes for Series Recordings - ksooo - 2015-07-24

Don't know where to start given the amount of ideas. ;-)

First, I do not really like the idea to duplicate several EPG_TAG data fields into several other add-on data structures. PVR_TIMER already contains a field for a EPG event uid. Why don't we just use this id to query Kodi's local EPG database for the data of interest on demand? What might be still missing is an API function to obtain an EPG_TAG for a given epg event uid. The latter would be needed to directly obtain data from the back-end via the add-on, because often Kodi has a much smaller local EPG data window than the back-end has (this is at least the case for tvheadend).

RE: Planned API changes for Series Recordings - scarecrow420 - 2015-07-24

(2015-07-24, 14:01)metaron Wrote: Sounds to me like a good idea. It would need:
  • a PVR_TIMER_TYPE_SUPPORTS_MAX_RECORDINGS flag in PVR_TIMER_TYPE
  • an iMaxRecordings variable in PVR_TIMER
  • a new spinner "Maximum Recordings" appearing directly below Lifetime in the TimerSettings dialog
  • conditional visibility for "Maximum Recordings"
  • The following Spinner options with default setting 'Unlimited':
    • Unlimited
    • 1
    • ...
    • 100
My feeling is the list doesn't need to be client configurable. Would a list like this work for WMC?
(An unlisted value of iMaxRecordings could be added to the spinner on the fly as was recently done for dates)

It could be made partially configurable (with a range specified by the client), or for API consistency fully configurable but I know there was some concern about list memory usage. Personally I think this is overkill. @ksooo, @janbar, @opdenkamp, @jalle19 what do you think?

Another problem I can see is that this setting might only be valid for some cases of 'Lifetime'.
For Mythtv, in conjunction with a list like this, Lifetime could be changed to:
  • Recordings never expire
  • Allow recordings to expire
  • Record new and expire old
And they would all be valid (well not for unlimited), but does this also work for wmc?

There are already cases for mythtv where 'AnyChannel' isn't valid, but still appears in the channel list, so maybe a precedent has already been set regarding invalid combinations.
the addon should define the list values just like all the other fields added in the latest API changes. In WMC for example we can only support 1 to 7, 10, "latest episodes" and unlimited so a hardcoded list of 100 options would be just as bad as lifetime and priority fields were before we could setset tlist contents ourselves and essentially defeats the purpose of these series recording API support changes (ie that addons can each define their own acceptable values) .

I get what you mean about this setting possibly only applying to some lifetime selections but specifically in my addon at least this isn't the case (wmc always shows the limit field when showing lifetime) and it sounds like you've also highlighted how your addon could use lifetime and limit/max fields in conjunction to avoid that too. And then as you say, any channel sometimes shows when not required so it's not a huge deal anyway

RE: Planned API changes for Series Recordings - metaron - 2015-07-24

(2015-07-24, 17:17)scarecrow420 Wrote: the addon should define the list values just like all the other fields added in the latest API changes. In WMC for example we can only support 1 to 7, 10, "latest episodes" and unlimited so a hardcoded list of 100 options would be just as bad as lifetime and priority fields were before we could setset tlist contents ourselves and essentially defeats the purpose of these series recording API support changes (ie that addons can each define their own acceptable values) .
Ok - I can see that an addon defined list makes sense here as well.

You talk about 'limit' and I talk about 'max recordings' due to differences in terminology between mythtv and wmc I guess. (I'm not familiar with wmc). What would your preferred title for this new field be? "Limit" "Keep up to" or something else.

RE: Planned API changes for Series Recordings - scarecrow420 - 2015-07-25

"Keep up to" is how wmc displays it on screen. "RecordingLimit" is the name of the field in their code base. Honestly I'm not too fussed since Kodi terminology already differs to WMC (eg lifetime vs keep, timer vs scheduled recording etc). As long as the field is directly below lifetime in the GUI and has a name that makes sense I think it's fine. "recording limit" or "max recordings" sounds fine. I probably tend to say don't say "Keep up to" since we don't name lifetime "Keep" so the need for "keep" terminology is probably unsuitable/inconsistent with lifetime

RE: Planned API changes for Series Recordings - metaron - 2015-07-25

(2015-07-24, 16:46)ksooo Wrote: Don't know where to start given the amount of ideas. ;-)

First, I do not really like the idea to duplicate several EPG_TAG data fields into several other add-on data structures. PVR_TIMER already contains a field for a EPG event uid. Why don't we just use this id to query Kodi's local EPG database for the data of interest on demand? What might be still missing is an API function to obtain an EPG_TAG for a given epg event uid. The latter would be needed to directly obtain data from the back-end via the add-on, because often Kodi has a much smaller local EPG data window than the back-end has (this is at least the case for tvheadend).

I think the data fields you're talking about are strEpisodeName (aka subtitle), iSeriesNumber, iEpisodeNumber, iEpisodePartNumber and iYear.
My reasons for wanting to include these are as follows:
  1. To make subtitle, season and episode available to ttvdb scraper in the filename via pvr:// (so it can find TV series)
  2. To make year available to imdb scraper in the filename via pvr:// (so it finds the correct film re-make)
  3. To make information available in a consistent way for all three methods (EPG/Timer/Recording), so Kodi Core / skins can adopt consistent and appropriate data display formats.

EPG tag extraction method
I can see that it would be good to have the facility to request EPG_TAG data on a recording. This could form the basis for a 'backend data scraper', as an alternative to IMDB/TTVDB, which I have seen asked after on the forum.
Are you suggesting I add it as another 'good idea', or do you want to PR it separately Wink

While requesting a full EPG tag from the database or backend would provide access to all the relevant data, it seems inefficient (slow?) for obtaining just season/episode/year to construct a ttvdb/imdb scraper compatible filename for the pvr:// filesystem. I have similar performance concerns using it to obtain episode subtitles, which really need to be presented in all subordinate timer/recording lists.

Defining and freezing the API and implementing this new function in the addons will probably also take a while.

Hack it into 'title'
Another approach is for the addons to 'hack' subtitle/season/episode into recording and timer titles. This is what pvr.mythtv has done for a long time for subtitle and what my 'hack' does with season/episode to get ttvdb scraping working.

The problem here is it doesn't allow PVR core to separate it out: When setting a repeating timer title, you just want "title". For a subordinate timer or a recording you want "title (subtitle)" or maybe "SxxEyy (subtitle)" when 'group timers' is on.
In addition the format you want in a list display probably isn't the format you need for a scraper compatible filename.
Providing the data separately allows PVR core/skins to ensure a compatible and consistent format and display philosophy across all areas.

Current proposal - extra PVR_RECORDING/PVR_TIMER attributes
This is quick and easy for an addon to implement: just populate the new fields if the data is available. No new function for EPG extraction to write and test.

What's your main concern here? Interface duplication or the size of the PVR_TIMER or PVR_RECORDING data structures?

Thinking about the detail I can't see much need for iEpisodePartNumber as a separate field. Most listings data seems to identify parts1&2 of a split episode as separate episodes, with the part embedded in the episode title (S01E01 Broken Bow Part 1, S01E02 Broken Bow Part 2), so I think this could comfortably be dropped.

It would probably also make sense to reduce the size of strTitle from 1000 to 512 chars if strEpisodeName is added to take the subtitle. Do you think titles more than 512 characters long without a subtitle exist?
Movie: "Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb" = 51 chars
Longest title in current EPG: "Nelson's Caribbean Hell-Hole: An Eighteenth Century Navy Graveyard Uncovered" = 78 chars

Conclusion
@ksooo and others: Please keep giving me a hard time about these ideas if your gut tells you they won't work. If I can't justify them to your satisfaction then I don't want them to go in. If I manage to convince you, probably they are good enough for a PR.

RE: Planned API changes for Series Recordings - ksooo - 2015-07-25

Quote:While requesting a full EPG tag from the database or backend would provide access to all the relevant data, it seems inefficient (slow?) for obtaining just .... I have similar performance concerns using it to obtain episode subtitles, which really need to be presented in all subordinate timer/recording lists.

In general, Kodi's local EPG container should have all the relevant data as Kodi obtains those from time time to time using PVR API addon function GetEpg. The latter is a bulk operation, obtaining all events for a given time frame from the backend. If currently some data useful for Kodi is generally missing because struct EPG_TAG has no field for it, we should add it there.

The new function I'm talking about is just for exceptional cases, where the data are not available locally. Example: Today I schedule a repeating timer, tvheadend's epg db has data until end of August, Kodi requests (and holds) only EPG data until End of July. (numbers are just examples). tvheadend schedules timers for events until end auf August, those timers appear in Kodi. Today Kodi cannot display any EPG details for the events for timers going off after End of July. For this very special cases I thought of the new function.

Quote:I can see that it would be good to have the facility to request EPG_TAG data on a recording. ... Are you suggesting I add it as another 'good idea', or do you want to PR it separately

Add it as another good(?) idea, please.

Quote:Another approach is for the addons to 'hack' subtitle/season/episode into recording and timer titles.

No! This is a hack. We should avoid that kind of stuff.

Quote:Current proposal - extra PVR_RECORDING/PVR_TIMER attributes ... What's your main concern here? Interface duplication or the size of the PVR_TIMER or PVR_RECORDING data structures?

Both + bloated API. We should try to not make it to complex.

Quote:Please keep giving me a hard time about these ideas

I'll try my very best... :-) Keep up the good work and don't give up on me being PITA from time to time.

RE: Planned API changes for Series Recordings - metaron - 2015-07-25

(2015-07-25, 17:03)ksooo Wrote:
Quote:Current proposal - extra PVR_RECORDING/PVR_TIMER attributes ... What's your main concern here? Interface duplication or the size of the PVR_TIMER or PVR_RECORDING data structures?

Both + bloated API. We should try to not make it to complex.

Looking at PVR_RECORDING and PVR_TIMER, can I suggest a compromise which appears to be in keeping with the level of data already in these structures:
  • PVR_TIMER - Only add strEpisodeName

    No-one is going to scrape from a timer so season/episode and year aren't that important. Yes it would be possible to use EPG data to add 'subtitle' where current guide data is available, but it would be the only field presented in the list of timers which was obtained in a different way. Imo this would add rather than reduce API complexity.

    Other data (season/episode/year/plot/actor/director etc...) which would be useful on an as yet not implemented 'info on upcoming recording' screen can be obtained from the EPG database, supplemented by a new GetTimerEPGInfo function as needed.
  • PVR_RECORDING - Add strEpisodeName, iSeriesNumber, iEpisodeNumber and iYear; (not iEpisodePartNumber)

    PVR_RECORDING already contains a lot of other information (Plot, PlotSummary, GenreType, GenreSubType, Thumbnail, Fanart...) which is used in existing screens to present information on the recording. To my mind not having season/episode numbering and subtitle available in a dataset when you already have plot is just wrong.
    Year might be considered less critical, but in order to 'scrape' imdb for movies properly this needs to be there as well.

    For getting even more data (scraping), a new GetRecordingEPGInfo function can be used. This would fill the gaps in the PVR_RECORDING structure for filling video database entries.

I'll adjust my branch along these lines and make 'MAX_RECORDINGS' an addon definable list rather than a spinner.
I'll also add new PVR_ERROR functions for GetTimerEPGInfo and GetRecordingEPGInfo to the PVRClient structure.

@ksooo, does this work for you?
If you're feeling a little less uncomfortable I'll PR this API change and move the discussion to github.
EDIT: I'd like some feedback on my GetTimerEPGInfo and GetRecordingEPGInfo functions before I do this (see next post)

This is probably enough 'good ideas' to be getting on with, but if there are any more (or further objections/suggestions) please shout.

RE: Planned API changes for Series Recordings - metaron - 2015-07-25

@ksooo
I've had some more thoughts about a GetTimerEPGInfo function.

Subordinate timers will relate directly to EPG entries. For those which are outside kodi's EPG range but in backend EPG range, getting a specific EPG entry makes perfect sense.

For complex search timers, an EPG event isn't always directly applicable (I'm thinking of search rules like 'convert movies to HD'). Inserting information into the EPG database in this case seems wrong.

For repeating timers what you really want is information on the series as a whole, not a specific episode. There may be an EPG record used to set up the timer, but that could be very old.

Manual timers may associate to an EPG entry, but possibly more than one. If so, which should be used?

The issue is that Kodi core doesn't necessarily know which timers will associate to an EPG entry and which won't. It would have to ask and be told 'yes/no/never', then keep notes. The backend/client is the master for this information.

It might be better for a client to 'push' EPG information outside the bulk EPG transfer range where applicable, then simply populate the EPG tag in the timer when it has done so.
  • Is this possible?
  • If so, how could it be done?
  • Would the EPG database be able to cope with 'straggling' entries?
  • If they exist, would the EPG timeline automatically extend to include them.
  • This might be a good idea, but could it kill performance on slow frontends like RPi?

I think extra information for 'non-epg' related timers should be considered out of scope for now. If necessary extra PVR_TIMER fields could be added in the future, but to me this doesn't feel like a good idea yet.

RE: Planned API changes for Series Recordings - metaron - 2015-07-26

@ksooo - I've just seen the comments you left on Github this morning (mental note - must check e-mail before forum!).
I will try and address them tomorrow.
I've submitted https://github.com/xbmc/xbmc/pull/7626 so there is a place to make and reply to specific comments.

If there are any more 'good ideas' post here.

RE: Planned API changes for Series Recordings - metaron - 2015-07-30

Transferred from github discussion https://github.com/xbmc/xbmc/pull/7635#issuecomment-126363158
Quote: ryangribble/scarecrow420
Since you asked for my opinion,

In WMC concepts the AnyTime flag is only used on EPG based recordings. If user creates a timer for "Friends" at 8pm from the EPG, by default it will record "Friends" at 8pm on whatever days of week are input. If AnyTime is enabled then it will record Friends on Any Timeslot (eg a rerun at 2am or whatever). There is no ability to set a specific start or end time, it is either the specific airtime of the show, or anytime that show airs.

In general to maintain my desired behaviour, assuming you add attributes for 4 things (start time, end time, and anytime boolean for each) I would just want to be able to enable 1 boolean and disable the other 3 fields. Then I think it would just maintain the behaviour as it is right now of having a AnyTime radio button on my Epg based timer types that can be toggled on/off, but never triggers a start or end time to be presented to the user.

Hope that clarifies my usage, let me know if this is how your changes will behave. If not I can still likely work around thigns although it isnt ideal to present the user with start/end time boxes they can edit, when those actually will have no effect
Quote: metaron-uk/metaron
@ryangribble - Re-reading your description, what would be really nice is if you could get the clock to display but be greyed out - but the API can't do that (yet). If you can think of a way to grey-out options selectively by type, I'd like to see this for mythtv as well...
Quote: ryangribble/scarecrow420
Well just like we are using attributes to control if a field is hidden or shown, I assume it'd be possible to grey out fields based on yet more attributes (just like how when readonly attribute is set, all fields are greyed out). Eg StartTimeIsReadOnly and EndTimeIsReadOnly. These could cause the field to be made readonly then when it is shown/hidden by radio buttons it is still in the control of the addon if it can be edited. A similar case could exist for other fields eg for me the Timer Name field would be uneditable on Epg based timers but editable on manual ones

This would be ideal but is definitely a bell or whistle

I wondered about a separate bit mask rather than just more attributes, but yes I agree - at this stage, gilding the lilly.

RE: Planned API changes for Series Recordings - metaron - 2015-08-03

For the information of any PVR addon maintainers, https://github.com/xbmc/xbmc/pull/7626 is now nearing completion, currrently containing the following 4 changes and rolling the PVR API version to 3.0.0:
  • Separate Anytime control for start/end using booleans rather than start=end=0
  • Season/episode/year/EpisodeName provided separately for recordings (scraper and list sorting improvements)
  • Ability to choose if a timer type appears in the create list list below the timer list 'Add...' entry or the EPG 'Add Customer Timer' menu option
  • Extra 'Max Recordings' list in the Timer Types dialog (if a backend needs it)

Comments, constructive criticism and offers of assistance would be gratefully appreciated over on Github.

I was asked previously on the mythtv support form to include 'Recording Templates' if I got the chance.
I haven't forgotten, but my thinking is that this might be better handled by the mythtv addon rather than kodi core.
It would need a bit of thought to work out a 'sensible' way to do this: (maybe associate a template with each recording group, or each timer type?). Anyhow, something for 'next time' imo.

RE: Planned API changes for Series Recordings - scarecrow420 - 2015-08-05

Yeah I'd suggest using the Kodi recording group field/function to implement these recording templates

Planned API changes for Series Recordings - puenktchen - 2015-08-08

@ksooo
I know your changes have to be implemented by the pvr addon maintainers, but without that it should not break existing functionality, should it?! Right now with the nightly builds and MediaPortal pvr addon, Kodi crashes when i hit enter on existing schedule Confused