Quick start

Actually you should read this entire document before starting to work with VDR plugins, but you probably want to see something happening right away ;-)

So, for a quick demonstration of the plugin system, there is a sample plugin called "hello" that comes with the VDR source. To test drive this one, do the following:

• change into the VDR source directory
• make the VDR program with your usual REMOTE=... (and maybe other) options
• do make plugins to build the plugin
• run VDR with vdr -V to see the version information
• run VDR with vdr -h to see the command line options
• run VDR with vdr -Phello
• open VDR's main menu and select the Hello item
• open the Setup menu from VDR's main menu and select Plugins

The name of the plugin

One of the first things to consider when writing a VDR plugin is giving the thing a proper name. This name will be used in the VDR command line in order to load the plugin, and will also be the name of the plugin's source directory, as well as part of the final library name.

The plugin's name should typically be as short as possible. Three letter abbreviations like dvd (for a DVD player) or mp3 (for an MP3 player) would be good choices. It is also recommended that the name consists of only lowercase letters and digits. No other characters should be used here.

A plugin can access its name through the (non virtual) member function

const char *Name(void);

By default plugins are located in a directory named PLUGINS below the VDR source directory. Inside this directory the following subdirectory structure is used:

VDR/PLUGINS/src VDR/PLUGINS/src/hello VDR/PLUGINS/lib VDR/PLUGINS/lib/libvdr-hello.so.1.1.0

The src directory contains one subdirectory for each plugin, which carries the name of that plugin (in the above example that would be hello). What's inside the individual source directory of a plugin is entirely up to the author of that plugin. The only prerequisites are that there is a Makefile that provides the targets all and clean, and that a call to make all actually produces a dynamically loadable library file for that plugin (we'll get to the details later).

The lib directory contains the dynamically loadable libraries of all available plugins. Note that the names of these files are created by concatenating

libvdr-	hello	.so.	1.1.0
VDR plugin library prefix	name of the plugin	shared object indicator	VDR version number this plugin was compiled for

The plugin library files can be stored in any directory. If the default organization is not used, the path to the plugin directory has be be given to VDR through the -L option.

The VDR Makefile contains the target plugins, which calls make all in every directory found under VDR/PLUGINS/src, plus the target plugins-clean, which calls make clean in each of these directories.

Call the Perl script newplugin from the VDR source directory to create a new plugin directory with a Makefile and a main source file implementing the basic derived plugin class. You will also find a README file there with some inital text, where you should fill in actual information about your project. A HISTORY file is set up with an "Initial revision" entry. As your project evolves, you should add the changes here with date and version number.

newplugin also creates a copy of the GPL license file COPYING, assuming that you will release your work under that license. Change this if you have other plans.

The constructor and destructor of a plugin are defined as

cPlugin(void); virtual ~cPlugin();

Every plugin must have a version number of its own, which does not necessarily have to be in any way related to the VDR version number. VDR requests a plugin's version number through a call to the function

virtual const char *Version(void) = 0;

Since this is a "pure" virtual function, any derived plugin class must implement it. The returned string should identify this version of the plugin. Typically this would be something like "0.0.1", but it may also contain other information, like for instance "0.0.1pre2" or the like. The string should only be as long as really necessary, and shall not contain the plugin's name itself. Here's an example:

static const char *VERSION = "0.0.1"; const char *cPluginHello::Version(void) { return VERSION; }

Note that the definition of the version number is expected to be located in the main source file, and must be written as

static const char *VERSION = ...

In order to tell the user what exactly a plugin does, it must implement the function

virtual const char *Description(void) = 0;

which returns a short, one line description of the plugin's purpose:

static const char *DESCRIPTION = "A friendly greeting"; virtual const char *Description(void) { return tr(DESCRIPTION); }

A VDR plugin can have command line arguments just like any normal program. If a plugin wants to react on command line arguments, it needs to implement the function

virtual bool ProcessArgs(int argc, char *argv[]);

The parameters argc and argv have exactly the same meaning as in a normal C program's main() function. argv[0] contains the name of the plugin (as given in the -P option of the vdr call).

Each plugin has its own set of command line options, which are totally independent from those of any other plugin or VDR itself.

You can use the getopt() or getopt_long() function to process these arguments. As with any normal C program, the strings pointed to by argv will survive the entire lifetime of the plugin, so it is safe to store pointers to these values inside the plugin. Here's an example:

bool cPluginHello::ProcessArgs(int argc, char *argv[]) { // Implement command line argument processing here if applicable. static struct option long_options[] = { { "aaa", required_argument, NULL, 'a' }, { "bbb", no_argument, NULL, 'b' }, { NULL } }; int c; while ((c = getopt_long(argc, argv, "a:b", long_options, NULL)) != -1) { switch (c) { case 'a': option_a = optarg; break; case 'b': option_b = true; break; default: return false; } } return true; }

If a plugin accepts command line options, it should implement the function

virtual const char *CommandLineHelp(void);

which will be called if the user enters the -h option when starting VDR. The returned string should contain the command line help for this plugin, formatted in the same way as done by VDR itself:

const char *cPluginHello::CommandLineHelp(void) { // Return a string that describes all known command line options. return " -a ABC, --aaa=ABC do something nice with ABC\n" " -b, --bbb activate 'plan B'\n"; }

If the plugin implements a feature that the user shall be able to access from VDR's main menu, it needs to implement the function

virtual const char *MainMenuEntry(void);

The default implementation returns a NULL pointer, which means that this plugin will not have an item in the main menu. Here's an example of a plugin that will have a main menu item:

static const char *MAINMENUENTRY = "Hello"; const char *cPluginHello::MainMenuEntry(void) { return tr(MAINMENUENTRY); }

If the user selects the main menu entry of a plugin, VDR calls the function

virtual cOsdObject *MainMenuAction(void);

which can do one of three things:

Housekeeping

From time to time a plugin may want to do some regular tasks, like cleaning up some files or other things. In order to do this it can implement the function

virtual void Housekeeping(void);

which gets called when VDR is otherwise idle. The intervals between subsequent calls to this function are not defined. There may be several hours between two calls (if, for instance, there are recordings or replays going on) or they may be as close as ten seconds. The only thing that is guaranteed is that there are at least ten seconds between two subsequent calls to the Housekeeping() function of the same plugin.

If a plugin requires its own setup parameters, it needs to implement the following functions to handle these parameters:

virtual cMenuSetupPage *SetupMenu(void); virtual bool SetupParse(const char *Name, const char *Value);

To implement a Setup menu, a plugin needs to derive a class from cMenuSetupPage and implement its constructor and the pure virtual Store() member function:

int GreetingTime = 3; int UseAlternateGreeting = false; class cMenuSetupHello : public cMenuSetupPage { private: int newGreetingTime; int newUseAlternateGreeting; protected: virtual void Store(void); public: cMenuSetupHello(void); }; cMenuSetupHello::cMenuSetupHello(void) { newGreetingTime = GreetingTime; newUseAlternateGreeting = UseAlternateGreeting; Add(new cMenuEditIntItem( tr("Greeting time (s)"), &newGreetingTime)); Add(new cMenuEditBoolItem(tr("Use alternate greeting"), &newUseAlternateGreeting)); } void cMenuSetupHello::Store(void) { SetupStore("GreetingTime", GreetingTime = newGreetingTime); SetupStore("UseAlternateGreeting", UseAlternateGreeting = newUseAlternateGreeting); }

In this example we have two global setup parameters (GreetingTime and UseAlternateGreeting). The constructor initializes two private members with the values of these parameters, so that the Setup menu can work with temporary copies (in order to discard any changes if the user doesn't confirm them by pressing the "Ok" button). After this the constructor adds the appropriate menu items, using internationalized texts and the addresses of the temporary variables. That's all there is to inizialize a Setup menu - the rest will be done by the core VDR code.

Once the user has pressed the "Ok" button to confirm the changes, the Store() function will be called, in which all setup parameters must be actually stored in VDR's global setup data. This is done by calling the SetupStore() function for each of the parameters. The Name string given here will be used to identify the parameter in VDR's setup.conf file, and will be automatically prepended with the plugin's name.

If a plugin displays texts to the user, it should implement internationalized versions of these texts and call the function

void RegisterI18n(const tI18nPhrase * const Phrases);

to register them with VDR's internationalization mechanism.

Plugins are loaded into VDR using the command line option -P, as in

vdr -Phello

If the plugin accepts command line options, they are given as part of the argument to the -P option, which then has to be enclosed in quotes:

vdr -P"hello -a abc -b"

Any number of plugins can be loaded this way, each with its own -P option:

vdr -P"hello -a abc -b" -Pdvd -Pmp3

If you are not starting VDR from the VDR source directory (and thus your plugins cannot be found at their default location) you need to tell VDR the location of the plugins through the -L option:

vdr -L/usr/lib/vdr -Phello

There can be any number of -L options, and each of them will apply to the -P options following it.

Status monitor

If a plugin wants to get informed on various events in VDR, it can derive a class from cStatus, as in

#include <vdr/status.h> class cMyStatusMonitor : public cStatus { protected: virtual void ChannelSwitch(const cDevice *Device, int ChannelNumber); }; void cMyStatusMonitor::ChannelSwitch(const cDevice *Device, int ChannelNumber) { if (ChannelNumber) dsyslog("channel switched to %d on DVB %d", ChannelNumber, Device->CardIndex()); else dsyslog("about to switch channel on DVB %d", Device->CardIndex()); }

An object of this class will be informed whenever the channel is switched on one of the DVB devices. It could be used in a plugin like this:

#include <vdr/plugin.h> class cPluginStatus : public cPlugin { private: cMyStatusMonitor *statusMonitor; public: cPluginStatus(void); virtual ~cPluginStatus(); ... virtual bool Start(void); ... }; cPluginStatus::cPluginStatus(void) { statusMonitor = NULL; } cPluginStatus::~cPluginStatus() { delete statusMonitor; } bool cPluginStatus::Start(void) { statusMonitor = new cMyStatusMonitor; return true; }

Note that the actual object is created in the Start() function, not in the constructor! It is also important to delete the object in the destructor, in order to avoid memory leaks.

A Plugin can implement any number of cStatus derived objects, and once the plugin has been started it may create and delete them as necessary. No further action apart from creating an object derived from cStatus is necessary. VDR will automatically hook it into a list of status monitors, with their individual virtual member functions being called in the same sequence as the objects were created.

Implementing a player is a two step process. First you need the actual player class, which is derived from the abstract cPlayer:

#include <vdr/player.h> class cMyPlayer : public cPlayer { protected: virtual void Activate(bool On); public: cMyPlayer(void); virtual ~cMyPlayer(); };

What exactly you do in this class is entirely up to you. If you want to run a separate thread which, e.g., reads data from a file, you can additionally derive your class from cThread and implement the necessary functionality:

#include <vdr/player.h> class cMyPlayer : public cPlayer, cThread { protected: virtual void Activate(bool On); virtual void Action(void); public: cMyPlayer(void); virtual ~cMyPlayer(); };

Take a look at the files player.h and dvbplayer.c to see how VDR implements its own player for the VDR recordings.

To play the video data, the player needs to call its member function

int PlayVideo(const uchar *Data, int Length);

where Data points to a block of Length bytes of a PES data stream. There are no prerequisites regarding the length or alignment of an individual block of data. The sum of all blocks must simply result in the desired video data stream, and it must be delivered fast enough so that the DVB device doesn't run out of data. To avoid busy loops the player should call its member function

bool DevicePoll(cPoller &Poller, int TimeoutMs = 0);

to determine whether the device is ready for further data.

If the player can provide more than a single audio track, it can implement the following functions to make them available:

virtual int NumAudioTracks(void) const; virtual const char **GetAudioTracks(int *CurrentTrack = NULL); virtual void SetAudioTrack(int Index);

If there is an additional audio track that has to be replayed with external hardware, the player shall call its member function

void PlayAudio(const uchar *Data, int Length);

where Data points to a complete audio PES packet of Length bytes.

The second part needed here is a control object that receives user input from the main program loop and reacts on this by telling the player what to do:

#include <vdr/player.h> class cMyControl : public cControl { private: cMyPlayer *player; public: cMyControl(void); virtual ~cMyControl(); virtual void Hide(void); virtual eOSState ProcessKey(eKeys Key); };

cMyControl shall create an object of type cMyPlayer and hand over a pointer to it to the cControl base class, so that it can be later attached to the primary DVB device:

cMyControl::cMyControl(void) :cControl(player = new cMyPlayer) { }

cMyControl will receive the user's key presses through the ProcessKey() function. It will get all button presses, except for the volume control buttons (kVolUp, kVolDn, kMute), the power button (kPower) and the menu button (kMenu). If the user has not pressed a button for a while (which is typically in the area of about one second), ProcessKey() will be called with kNone, so that the cMyControl gets a chance to check whether its player is still active. Once the player has become inactive (because the user has decided to stop it or the DVB device has detached it), ProcessKey() must return osEnd to make the main program loop shut down the player control.

A derived cControl must implement the Hide() function, in which it has to hide itself from the OSD, in case it uses it. Hide() may be called at any time, and it may be called even if the cControl is not visible at the moment. The reason for this is that the Menu button shall always bring up the main VDR menu, so any active cControl needs to be hidden when that button is pressed.

Finally, to get things going, a plugin that implements a player (and the surrounding infrastructure like displaying a list of playable stuff etc) simply has to call the static function cControl::Launch() with the player control object, as in

cControl::Launch(new cMyControl);

Ownership of the MyControl object is handed over to the VDR core code, so the plugin should not keep a pointer to it, because VDR will destroy the object whenever it sees fit (for instance because a recording shall start that needs to use the primary DVB device, or the user decides to start a different replay).

The cPlayer class has a member function

void DeviceStillPicture(const uchar *Data, int Length);

which can be called to display a still picture. VDR uses this function when handling its editing marks. A special case of a "player" might use this function to implement a "picture viewer".

For detailed information on how to implement your own player, please take a look at VDR's cDvbPlayer and cDvbPlayerControl classes.

User interface

In order for a new player to nicely "blend in" to the overall VDR appearance it is recommended that it implements the same functionality with the same keys as the VDR player does (as far as this is possible and makes sense). The main points to consider here are

• The Ok button shall bring up some display that indicates what is currently being played, and what the status of this replay session is. As an alternative (for instance with a DVD player) it may display a player specific menu, from which the user can select certain options.
• The Up, Down, Left and Right buttons shall control Play, Pause, Fast Rewind and Fast Forward, respectively (provided that this particular player can implement these functions) if the player is not currently showing any menu. If there is a menu, they shall allow the user to navigate in the menu. The dedicated Play, Pause, FastRew and FastFwd keys shall always result in their specific functionality.
• The Green and Yellow buttons shall skip back- and forward by an amount of time suitable for this player (provided that this particular player can implement these functions).
• The Blue and Stop button shall immediately stop the replay session.

Receivers

In order to receive any kind of data from a cDevice, a plugin must set up an object derived from the cReceiver class:

#include <vdr/receiver.h> class cMyReceiver : public cReceiver, cThread { protected: virtual void Activate(bool On); virtual void Receive(uchar *Data, int Length); public: cMyReceiver(int Pid); }; cMyReceiver::cMyReceiver(int Pid) :cReceiver(0, -1, 1, Pid) { } void cMyReceiver::Activate(bool On) { // start your own thread for processing the received data } void cMyReceiver::Receive(uchar *Data, int Length) { // buffer the data for processing in a separate thread }

See the comments in VDR/receiver.h for details about the various member functions of cReceiver.

The above example sets up a receiver that wants to receive data from only one PID (for example the Teletext PID). In order to not interfere with other recording operations, it sets its priority to -1 (any negative value will allow a cReceiver to be detached from its cDevice at any time.

Once a cReceiver has been created, it needs to be attached to a cDevice:

cMyReceiver *Receiver = new cMyReceiver(123); cDevice::ActualDevice()->AttachReceiver(Receiver);

Noteh the use of cDevice::ActualDevice() here, which makes sure that the receiver is attached to the device that actually receives the current live video stream (this may be different from the primary device in case of Transfer Mode).

Most of the time a plugin should be able to access the OSD through the standard mechanisms also used by VDR itself. However, these set up the OSD in a manner of textual rows and columns, and automatically set the various windows and color depths.

If a plugin needs to have total control over the OSD, it can call the static function

#include <vdr/osd.h> cOsdBase *MyOsd = cOsd::OpenRaw(x, y);

where x and y are the coordinates of the upper left corner of the OSD area on the screen. Such a "raw" OSD doesn't display anything yet, so you need to at least call the function

MyOsd->Create(...);

By default VDR is based on using DVB PCI cards that are supported by the LinuxDVB driver. However, a plugin can implement additional devices that can be used as sources of MPEG data for viewing or recording, and also as output devices for replaying. Such a device can be a physical card that is installed in the PC (like, for instance, an MPEG encoder card that allows the analog signal of a proprietary set-top box to be integrated into a VDR system; or an analog TV receiver card, which does the MPEG encoding "on the fly" - assuming your machine is fast enough), or just a software program that takes an MPEG data stream and displays it, for instance, on an existing graphics adapter.

To implement an additional device, a plugin must derive a class from cDevice:

#include <vdr/device.h> class cMyDevice : public cDevice { ... };

The derived class must implement several virtual functions, according to the abilities this new class of devices can provide. See the comments in the file VDR/device.h for more information on the various functions, and also VDR/dvbdevice.[hc] for details on the implementation of the cDvbDevice, which is used to access the DVB PCI cards.

Channel selection

If the new device can receive, it most likely needs to provide a way of selecting which channel it shall tune to:

virtual bool ProvidesSource(int Source) const; virtual bool ProvidesChannel(const cChannel *Channel, int Priority = -1, bool *NeedsDetachReceivers = NULL); virtual bool SetChannelDevice(const cChannel *Channel, bool LiveView);

These functions will be called with the desired source or channel and shall return whether this device can provide the requested source or channel and whether tuning to it was successful, repectively.

Audio selection

If the device can provide more than a single audio track, it can implement the following functions to make them available:

virtual int NumAudioTracksDevice(void) const; virtual const char **GetAudioTracksDevice(int *CurrentTrack = NULL) const; virtual void SetAudioTrackDevice(int Index);

Recording

A device that can be used for recording must implement the functions

virtual bool SetPid(cPidHandle *Handle, int Type, bool On); virtual bool OpenDvr(void); virtual void CloseDvr(void); virtual bool GetTSPacket(uchar *&Data);

which allow VDR to set the PIDs that shall be recorded, set up the device for recording (and shut it down again), and receive the MPEG data stream. The data must be delivered in the form of a Transport Stream (TS), which consists of packets that are all 188 bytes in size. Each call to GetTSPacket() must deliver exactly one such packet (if one is currently available).

If this device allows receiving several different data streams, it can implement

virtual bool CanBeReUsed(int Frequency, int Vpid);

to indicate this to VDR.

Replaying

The functions to implement replaying capabilites are

virtual bool HasDecoder(void) const; virtual bool CanReplay(void) const; virtual bool SetPlayMode(ePlayMode PlayMode);   virtual int64_t GetSTC(void); virtual void TrickSpeed(int Speed); virtual void Clear(void); virtual void Play(void); virtual void Freeze(void); virtual void Mute(void); virtual void StillPicture(const uchar *Data, int Length); virtual bool Poll(cPoller &Poller, int TimeoutMs = 0); virtual int PlayVideo(const uchar *Data, int Length);

In addition, the following functions may be implemented to provide further functionality:

virtual bool GrabImage(const char *FileName, bool Jpeg = true, int Quality = -1, int Si virtual void SetVideoFormat(bool VideoFormat16_9); virtual void SetVolumeDevice(int Volume);

Section Filtering If your device provides section filtering capabilities it can implement the function virtual int OpenFilter(u_short Pid, u_char Tid, u_char Mask); which must open a file handle that delivers section data for the given filter parameters. In order to actually start section handling, the device also needs to call the function StartSectionHandler(); from its constructor. See Filters on how to set up actual filters that can handle section data.

On Screen Display

If your device provides On Screen Display (OSD) capabilities (which every device that is supposed to be used as a primary device should do), it can implement the function

virtual cOsdBase *NewOsd(int x, int y);

which must return a newly created object of a derived cOsdBase class that implements the functions necessary to display OSD information on your device. The caller of this function will delete the object as soon as it is no longer needed.

Initializing new devices

A derived cDevice class shall implement a static function in which it determines whether the necessary hardware to run this sort of device is actually present in this machine (or whatever other prerequisites might be important), and then creates as many device objects as necessary. See VDR/dvbdevice.c for the implementation of the cDvbDevice initialize function.

There are many different ways to replay additional audio tracks, like Dolby Digital. So VDR offers a plugin interface that allows for the implementation of any kind of audio replay facility.

To implement a new audio output facility, simply derive a class from cAudio, as in

#include <vdr/audio.h> #include <vdr/thread.h> class cMyAudio : public cAudio, private cThread { private: virtual void Action(void); public: cMyAudio(void); virtual void Play(const uchar *Data, int Length); virtual void Mute(bool On); virtual void Clear(void); };

There are several ways to control the operation of VDR. The builtin methods are using the PC keyboard, a homebuilt RCU unit or the LIRC interface. Of course there may be many more ways you might think of to implement a remote control, so a plugin can use the cRemote class to do that.

The simplest method for a plugin to issue commands to VDR is to call the static function cRemote::Put(eKeys Key), as in

cRemote::Put(kUp);

In this case the plugin must do the mapping of whatever incoming signal or code it processes to the eKeys values itself. This makes sense if the incoming codes are well known and won't ever change.

In cases where the incoming codes are not known, or not all available keys may be supported by the actual remote control in use, you may want to derive your own remote control class from cRemote, as in

#include <vdr/remote.h> #include <vdr/thread.h> class cMyRemote : public cRemote, private cThread { private: virtual void Action(void); public: cMyRemote(const char *Name); virtual bool Initialize(void); };

Note that deriving from cThread is not required for a remote control class to work, but typically you may want to have a separate thread running that collects the input and delivers it to the cRemote base class.