PVR

Detailed Description

Class: kodi::addon::CInstancePVRClient

PVR client add-on instance

Kodi features powerful Live TV and video recording (DVR/PVR) abilities using a very flexible distributed application structure. That is, by leveraging other existing third-party PVR backend applications or DVR devices that specialize in receiving television signals and also support the same type of client–server model which Kodi uses, (following a frontend-backend design principle for separation of concerns), these PVR features in Kodi allow you to watch Live TV, listen to radio, view an EPG TV-Guide and schedule recordings, and also enables many other TV related features, all using Kodi as your primary interface once the initial pairing connection and configuration have been done.

Note

It is very important to understand that with "Live TV" in the reference to PVR in Kodi, we do not mean streaming video from the internet via websites providing free content or online services such as Netflix, Hulu, Vudu and similar, no matter if that content is actually streamed live or not. If that is what you are looking for then you might want to look into Video Addons for Kodi instead, (which again is not the same as the "PVR" or "Live TV" we discuss in this article), but remember that Kodi does not provide any video content or video streaming services.

The use of the PVR is based on the CInstancePVRClient.

Include the header #include <kodi/addon-instance/PVR.h> to use this class.

---

Here is an example of what the addon.xml.in would look like for an PVR addon:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="pvr.myspecialnamefor"
  version="1.0.0"
  name="My special PVR addon"
  provider-name="Your Name">
  <requires>@ADDON_DEPENDS@</requires>
  <extension
    point="kodi.pvrclient"
    library_@PLATFORM@="@LIBRARY_FILENAME@"/>
  <extension point="xbmc.addon.metadata">
    <summary lang="en_GB">My PVR addon addon</summary>
    <description lang="en_GB">My PVR addon description</description>
    <platform>@PLATFORM@</platform>
  </extension>
</addon>

At <extension point="kodi.pvrclient" ...> the basic instance definition is declared, this is intended to identify the addon as an PVR and to see its supported types:

Name	Description
point	The identification of the addon instance to inputstream is mandatory kodi.pvrclient. In addition, the instance declared in the first <extension ... /> is also the main type of addon.
library_@PLATFORM@	The runtime library used for the addon. This is usually declared by cmake and correctly displayed in the translated addon.xml.

Remarks

For more detailed description of the addon.xml, see also https://kodi.wiki/view/Addon.xml.

---

Example:

#include <kodi/addon-instance/PVR.h>
 
class CMyPVRClient : public ::kodi::addon::CInstancePVRClient
{
public:
  CMyPVRClient(KODI_HANDLE instance, const std::string& kodiVersion);
 
  PVR_ERROR GetCapabilities(kodi::addon::PVRCapabilities& capabilities) override;
  PVR_ERROR GetBackendName(std::string& name) override;
  PVR_ERROR GetBackendVersion(std::string& version) override;
 
  PVR_ERROR GetProvidersAmount(int& amount) override;
  PVR_ERROR GetProviders(std::vector<kodi::addon::PVRProvider>& providers) override;
  PVR_ERROR GetChannelsAmount(int& amount) override;
  PVR_ERROR GetChannels(bool radio, std::vector<kodi::addon::PVRChannel>& channels) override;
  PVR_ERROR GetChannelStreamProperties(const kodi::addon::PVRChannel&   channel,
                                       std::vector<kodi::addon::PVRStreamProperty>& properties) override;
 
private:
  std::vector<kodi::addon::PVRChannel> m_myChannels;
};
 
CMyPVRClient::CMyPVRClient(KODI_HANDLE instance, const std::string& kodiVersion)
  : CInstancePVRClient(instance, kodiVersion)
{
  kodi::addon::PVRChannel channel;
  channel.SetUniqueId(123);
  channel.SetChannelNumber(1);
  channel.SetChannelName("My test channel");
  m_myChannels.push_back(channel);
}
 
PVR_ERROR CMyPVRClient::GetCapabilities(kodi::addon::PVRCapabilities& capabilities)
{
  capabilities.SetSupportsTV(true);
  return PVR_ERROR_NO_ERROR;
}
 
PVR_ERROR CMyPVRClient::GetBackendName(std::string& name)
{
  name = "My special PVR client";
  return PVR_ERROR_NO_ERROR;
}
 
PVR_ERROR CMyPVRClient::GetBackendVersion(std::string& version)
{
  version = "1.0.0";
  return PVR_ERROR_NO_ERROR;
}
 
PVR_ERROR CMyInstance::GetProvidersAmount(int& amount)
{
  amount = m_myProviders.size();
  return PVR_ERROR_NO_ERROR;
}
 
PVR_ERROR CMyPVRClient::GetProviders(std::vector<kodi::addon::PVRProvider>& providers)
{
  providers = m_myProviders;
  return PVR_ERROR_NO_ERROR;
}
 
PVR_ERROR CMyInstance::GetChannelsAmount(int& amount)
{
  amount = m_myChannels.size();
  return PVR_ERROR_NO_ERROR;
}
 
PVR_ERROR CMyPVRClient::GetChannels(bool radio, std::vector<kodi::addon::PVRChannel>& channels)
{
  channels = m_myChannels;
  return PVR_ERROR_NO_ERROR;
}
 
PVR_ERROR CMyPVRClient::GetChannelStreamProperties(const kodi::addon::PVRChannel& channel,
                                                   std::vector<kodi::addon::PVRStreamProperty>& properties)
{
  if (channel.GetUniqueId() == 123)
  {
    properties.push_back(PVR_STREAM_PROPERTY_STREAMURL, "http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4");
    properties.push_back(PVR_STREAM_PROPERTY_ISREALTIMESTREAM, "true");
    return PVR_ERROR_NO_ERROR;
  }
  return PVR_ERROR_UNKNOWN;
}
 
...
 
//----------------------------------------------------------------------
 
class CMyAddon : public ::kodi::addon::CAddonBase
{
public:
  CMyAddon() = default;
  ADDON_STATUS CreateInstance(int instanceType,
                              const std::string& instanceID,
                              KODI_HANDLE instance,
                              const std::string& version,
                              KODI_HANDLE& addonInstance) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      const std::string& instanceID,
                                      KODI_HANDLE instance,
                                      const std::string& version,
                                      KODI_HANDLE& addonInstance)
{
  if (instanceType == ADDON_INSTANCE_PVR)
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my PVR client instance");
    addonInstance = new CMyPVRClient(instance, version);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

The destruction of the example class CMyPVRClient is called from Kodi's header. Manually deleting the add-on instance is not required.

Modules
	Definitions, structures and enumerators
	PVR client add-on instance definition values All PVR functions associated data structures.
	1. Basic functions
	Functions to manage the addon and get basic information about it These are e.g. GetCapabilities to know supported groups at this addon or the others to get information about the source of the PVR stream.
	2. Channels (required)
	Functions to get available TV or Radio channels These are mandatory functions for using this addon to get the available channels.
	3. Channel Groups (optional)
	Bring in this functions if you have set supportsChannelGroups to true This is used to divide available addon channels into groups, which can then be selected by the user.
	4. Channel edit (optional)
	Bring in this functions if you have set supportsChannelSettings to true or for OpenDialogChannelScan() set supportsChannelScan to true The support of this is a pure option and not mandatory.
	4. EPG methods (optional)
	PVR EPG methods These C ++ class functions of are intended for processing EPG information and for giving it to Kodi.
	5. Recordings (optional)
	PVR recording methods To transfer available recordings of the PVR backend and to allow possible playback.
	6. Timers (optional)
	PVR timer methods For editing and displaying timed work, such as video recording.
	7. Power management events (optional)
	Used to notify the pvr addon for power management events Used to allow any energy savings.
	8. Inputstream
	PVR Inputstream This includes functions that are used in the PVR inputstream.