Recording Service web API

From DVBViewer
(Redirected from Recording Service API)
Jump to: navigation, search

For question about the API post in Scripting Lounge / API

All functions should be working with Recording Service 1.33.1 or later.

If you find a Problem please report it in the Forum.


HTTP-Requests[edit]

All requests are done to the main web server of the Recording Service.

Most likely you have to do an authentification and you need the ip and web server port.

The answers from the Recording Service are xml files. If not described otherwise.


All http-requests use the base path api. This looks like this where the parts in "[ ]" have to be replaced with your values:

http://[user]:[password]@[IP]:[port]/api/

Reserved characters in the user and password part must use URL encoding.

Wikipedia Percent-encoding

User[edit]

There are two user accounts in the Recording Service. The normal user with full access and a limited gust user.

The gust user can only access API functions which aren't changing anything on the server. Or in other words read only access.

There are no fix user names to check for.

You have to use the status2 and there the rights value to determinate which access you have with the current user name.

Status informations[edit]

Version[edit]

The version of the service:

request

HTTP GET request

/api/version.html

response

<version iver="18939904">DVBViewer Recording Service 1.33.0.0 (beta) (PC-NAME)</version>
  • iver= MajorVersion x 224 + MinorVersion x 216 + Revision x 28 + Build
  • DVBViewer Recording Service fix name
  • 1.33.0.0 version number
  • (PC-NAME) the NetBIOS name on PC is "PC-NAME"

Status2[edit]

The Status of the service:

request

HTTP GET request

/api/status2.html

response

 <status>
   <timercount>0</timercount>
   <reccount>0</reccount>
   <nexttimer>-1</nexttimer>
   <nextrec>-1</nextrec>
   <streamclientcount>0</streamclientcount>
   <rtspclientcount>0</rtspclientcount>
   <unicastclientcount>0</unicastclientcount>
   <lastuiaccess>13</lastuiaccess>
   <standbyblock>1</standbyblock>
   <tunercount>0</tunercount>
   <streamtunercount>0</streamtunercount>
   <rectunercount>0</rectunercount>
   <epgudate>0</epgudate>
   <rights>full</rights>
   <recfiles>2</recfiles>
 	<recfolders>
 		<folder size="1445946646528" free="15966986240">
 			E:\Recorded TV
 		</folder>
 		<folder size="57404289024" free="3202850816">
 			C:\Users\Public\Recorded TV
 		</folder>
 	 </recfolders>
 </status>


  • timercount = number of active timers (all kinds)
  • reccount = number of ongoing recordings
  • nexttimer = time in seconds until the next timer (all kinds) starts (-1 = no timer will start)
  • nextrec = time in seconds until the next recording starts (-1 = no recording will start)
  • streamclientcount = number of streaming clients (receiving data continuously)
  • rtspclientcount = number of RTSP (Sat>IP) clients (may be more than 1 per DVBViewer instance)
  • unicastclientcount = number of unicast clients
  • lastuiaccess = time in seconds since the last web interface access (-1 = no access yet)
  • standbyblock = indicates whether the RS currently blocks standby (0 = no, 1 = yes)
  • tunercount = number of occupied tuners
  • streamtunercount = number of tuners occupied by streaming clients (may be more than 1 client per tuner)
  • rectunercount = number of tuners occupied by recordings (may intersect with streamtunercount)
  • epgudate = epg update state: 0 = inactive, 1 = active, 2 = waiting for a free tuner
  • rights = full (unlimited access to the API) read (only API functions which arn't changing anything permanently on the server are available)
  • recfiles = number of files in the recording data base
  • recfolders = avaiblable recording folders including folder, folder size, free disk space

Configuration files - settings[edit]

getconfigfile[edit]

Download of files from the configuration folder and its sub-folders

request

HTTP GET request

/api/getconfigfile.html?file=[path relative to the configuration folder]

example

Example (get service.xml from config sub folder):

http://[user:password@]IP[:port]/api/getconfigfile.html?file=config%5Cservice.xml (with %5C as URL encoded backslash)

Files containing the sub-string “userdata” in their name are purposely excluded and can not be downloaded.

You can use a * a wild card to get a list of files which are matching the pastern.

request

HTTP GET request

/api/getconfigfile.html?file=config/*.ini

The list is provided as UTF-8 coded plain text. Each filename in the list is followed by CR and LF.

setting[edit]

Access service.xml setting

request

HTTP GET request

/api/setting.html?sec=[section]&id=[identifier]&def=[def]

API provides an easy way to read settings from the file service.xml. It requires two parameters specifying the section and name (= identifier) of the value in question.

example

The following example gets the port of the Live Streaming Server:

http://[user:password@]IP[:port]/api/setting.html?sec=WebGeneral&id=StreamPort&def=7522


The line reads the value from the section sec with the identifier id and returns it as plain text. The def parameter is optional. It specifies a default that is returned if the entry does not exist. If def is not specified the API returns an empty string in this case.

Channel/Favourite list[edit]

getchannelsxml[edit]

xml channel list:

request

HTTP GET request

/api/getchannelsxml.html[?logo=1][&rtsp=1][&upnp=1][&subchannels=1] 
  • No parameter
A minimalistic channel list is returned with the appropriate root and category nodes.
A minimalistic channel entry consists of channel number, name, EPGID and favoriteID (=channelID) (without the name part).
  • rootsonly=1
Only root nodes are returned.
  • groupsonly=1
Root nodes and according category nodes are returned.
  • root=[Root name]
Only the entries matching the root name are returned.
  • group=[Group Name]
Only the matching entries for the category are returned.
  • id=[ChannelID 32/64bit]
Only the data for the channel with the channel ChannelID is returned.
  • epgid=[ChannelEPGID]
Only the data for the channel with the channel ChannelEPGID is returned.
  • number=[Channel number]
Only the data for the channel with the channel number is returned.
  • logo=1
The channel nodes contain the URL for the channel logo (if found). Attention: This may take a lot of time on the first call for extensive channel lists.
You can add ?height=[heightin pixels] to the image URL to get a version scaled of the image.
  • tuner=1
The channel nodes contain the tuner record.
  • rtsp=1
The RTSP(base)URL is returned as a node below the root node (if RTSP is activated) and the channel nodes contain the RTSP parameter which have to be combined with the rtspURL for a RTSP SETUP call.
  • upnp=1
The UPnPURL for LiveTV streaming is returned as a node below the root node (if UPnP is activated). The real URL for a channel can be calculated as upnpURL + [Channel number] + ".ts"
  • subchannels=1
If existing the audio sub channel are returned as „subchannel" nodes below the „channel" node. A subchannel entry consist of the channel name and the channel(favorite)ID. The other (for external programs interesting) parameters are covered by the parent channel node.
  • fav=1
lets the API enumerate the favorites at the top of the channel list, also apply to “rootsonly” and “groupsonly” mode, which means, the favorite groups resp. the favorite root are enumerated
  • favonly=1
enumerates the favorites, also apply to “rootsonly” and “groupsonly” mode, which means, the favorite groups resp. the favorite root are enumerated

Remarks: Favorites and channels appear as a contiguous virtual channel list, where favorites are numbered from -NoOfFavorites to -1 and channels from 0 to NoOfChannels-1. The negative favorite numbers can be used in URLs for channel selection (e. g. chid=-1). However, it is recommendable to rather use the channel ID than the index, because the latter may change in future Recording Service versions during runtime.

Mediafiles[edit]

mediafiles[edit]

Only files in the Media Libraries (see Recording Service Options) are included.

request

HTTP GET request

/api/mediafiles.html[?audio=1][?photo=1][&dirid={integer directory ID}][&thumbs=1]
  • audio=1 Lets the API list music directories and files instead of video.
  • photo=1 Lets the API list image directories and files instead of video.
  • dirid= Lets the API list the files in the directory identified by its ID. If this parameter is missing, the API lists the directories and sub-directories containing the requested media file type as linear list.
  • thumbs=1 Adds a relative URL referencing a video / photo thumbnail or album artwork to the file items.

Streaming[edit]

request HTTP GET request

/channels.m3u

request HTTP GET request

/rtspchannels.m3u

HLS[edit]

request HTTP GET request

/api/starthls.html?

request HTTP GET request

/master.m3u8?

WebM/TS/Flash[edit]

request HTTP GET request

/tv.html?

Recordings[edit]

recordings[edit]

recordings list:

request

HTTP GET request

/api/recordings.html[?utf8=]
  • utf8=1
Parameter utf8 the answer will be UTF8 encoded
  • nofilename=1
No (network) file name nodes are returned. → smaller download.
If nofilename is used a new property is added to the recording node: format="[file extension]". This is simply the file extension of the recording (.ts, .mpg etc.).
  • nodesc=1
The "desc" node is suppressed. → smaller download.
  • images=1
The baseURL for the thumbnails of the recordings is added to the root node as "imageURL".
The "recording" node contains the "image" subnode with the file name of the thumbnail.
If thumbnails are disabled or no thumbnail is available, this node will be omitted.
To download the image just combine the node value with the imageURL. You can use the "height" parameter (see above → GET channel logos) to downscale the image.
  • id=[recid]
Only the entry of the recording with "ID" is returned (if it exists). Can be combined with the above parameters.

recdelete[edit]

Deletes a specific recording

request

HTTP GET request

/api/recdelete.html?recid=id&delfile=1

Argument 'id' as provided by previous 'recordings.html' request

The API now returns a “423 Locked” status code if it is not possible to deleted the recording e.g. because it is a currently running recording.


EPG[edit]

EPG[edit]

get EPG data from the Recording Service

request

HTTP GET request

/api/epg.html?lvl=2[&channel={epgchannelID}][&start={floatDateTime}][&end={floatDateTime}][&search={term}&options={options}]

the parameters:

  • lvl=2 is mandatory
  • ch={epgchannelID} is optional
EPGChannelID = (TunerType + 1)*2^48 + NID*2^32 + TID*2^16 + SID
where:
SID = Service PID
TID = Stream ID
NID = Network ID
TunerType: 0=Cable 1=Satelite 2=Terrestial 3=ATSC
  • start and end: floatdatetime values (both . and , are accepted as decimal seperator).
It's best to get the epg in several steps (one day at a time as example), because it can be several megabytes of data.
  • search=[term]
specifies a search term in URL encoded format
  • options=
specifies the search options as character string containing one or more of the following letters that correspond to the EPG search options in the Web Interface:
  • T: Search in title.
  • S: Search in sub-title
  • D: Search in description
  • C: Case sensitive
  • R: Use regular expression
If the options parameter is missing or contains none of the letters TSD, the default is T.

Clear EPG[edit]

Clear EPG:

request

HTTP GET request

/api/epgclear.html?source=[Sources]

The numeric value [Sources] specifies the to be deleted EPG types as flags that can be or'ed (1 = DVB EPG 2 = MHW EPG, 4 = External EPG). If [Sources] is not specified the default is all EPG data (currently 7).

EPGimport[edit]

To add epg:

request

HTTP POST request

http://[user:password@]IP[:port]/cgi-bin/EPGimport

with valid EPG XML (same format like the api epg.html function).

Attention: returns a code 302 (Moved) when no file is posted, redirecting you to EPGimport/ which then returns a 404 (not found)

Attention: This call will set a a 30 sec. standby/hibernate block is if Block Standby/Hibernate... for Web interface actions is enabled.

Timer[edit]

Timer list[edit]

request

HTTP GET request

/api/timerlist.html[?utf8=2]
  • utf8=1 delivers the timer list with channel names that are not UTF-8-encoded, but according to the Windows default code page (CP_ACP), yielding invalid XML. Unfortunately this cannot be changed due to compatibility reasons.
  • utf8=2 results in a valid XML and UTF-8 encoded channel names

response

<Executeable>0</Executeable>

conflict with different timer, not enough capability hardware, timer are marked red in the web interface. This is only a rough prediction. Which timers exactly are defected can change at recording time.

But if all timers are marked as executable, all recordings shroud bi fine.

<Recording>1</Recording>

The recording is currently running.

Add a timer[edit]

How to add a timer:

request

HTTP GET request

/api/timeradd.html

With the following Params:

  • ch= The 32 Bit ChannelID deprecated
(ord(tunertype) + 1) shl 29 + APID shl 16 + SID;
in other words
(tunertype + 1) * 536870912 + APID * 65536 + SID
  • ch= The 64 Bit ChannelID
SID + APID x 2^16 + (tunertyp+1) x 2^29 + TransportstreamID x 2^32 + (orbitalposition x 10) x 2^48 + TV-radio-flag x 2^61


tunertype =
DVB-C = 0
DVB-S = 1
DVB-T = 2
ATSC = 3
DVB-IPTV = 4
APID = Audio-PID
SID = Service-ID
orbitalposition (in degree) * 10 (for DVB-T/C-Pseudo-degreenumbers 500/400)
TV-radio-flag = (2 Bit, 0 = not defined, 1 = TV, 2 = Radio)
calculated as: ord(tuner.Flags and cVideoService = 0) +1; where cVideoService = 8;
  • dor= The date (the integer part of the floatdatetime value) - mandatory
  • enable= 0/1 -> 1 = enabled - mandatory
  • start= / stop= The start and the endtime (integer, calculated by round(onlythetime * minsperday)) - mandatory
  • pre= / post= The time in minutes before and after the main recording (PreEPG and PostEPG in timerlist.html).
  • title= The name of the timer. see also "encoding".
  • encoding= The encoding of the timer (255 = UTF8). works for title, series and folder. - not used before .55
  • days= for repeating timers a 7 char string. Every char stands for a day of the week starting with monday. each char <> '-' means day is active. - optional
  • series= The series the timer belongs to. see also "encoding". - optional - not used before .55
  • action= The recording action 0 = Record, 1=tune. optional.
  • endact= The action after recoding. 0=None, 1=PowerOff, 2=Standby, 3=Hilbernate - optional
  • after= The name of the task to be executed after recording. caller is responsible that this internal/process task exists. - optional.
  • prio= The priority of the timer (0-100) 0=Lowest, 100=Highest. optional.
  • format= The recording format of the timer. 0=Audio only, 1=mpeg, 2=TS. - optional.
  • folder= The recording folder. The caller is responsible it is a folder from the defined recordings folders. - optional
  • audio= Record all Audiostreams of the channel. 0/1 - optional.
  • subs= Record DVBSubtitles. 0/1 - optional. only valid for TS
  • ttx= Record Teletext. 0/1 - optional. only valid for TS
  • eit= Record ETI EPG. 0/1 - optional. only valid for TS
  • allowdup=1 disabels the rejecting timers that are covered by already existing timer
  • pdc= Set a valid PDC value, to connect the Timer to a EPG entry.
  • epgevent= Set a valid EPG Event ID, to connect the Timer to a EPG entry (only used if the Twaak is set).
  • monitorpdc=1 enables EPG based timer corections. Needs a valid PDC value.
  • monforrec= only used with monitorpdc=1, 0: update of the start/end time from the EPG 1:Start / Stop by EPG running status

Edit a timer[edit]

To edit a timer:

request

HTTP GET request

/api/timeredit.html

same parameters as adding a timer. Additional:

  • id= The TimerID (see timerlist). mandatory.

IDs are only valid for the process runtime of the service. Make sure you get a current timerlist before editing.


remember all string values musst be url encoded!


Delete a timer[edit]

To delete a timer:

request

HTTP GET request

/api/timerdelete.html?id=xxxx[&delrecfile=x]

With the following Params:

  • id= The TimerID (see timerlist). mandatory.
IDs are only valid for the process runtime of the service. Make sure you get a current timerlist before editing.
  • delrecfile : 1 delete the (running) recording file too, if exists. (optional)


remember all string values musst be url encoded!

control[edit]

Recording Service tasks[edit]

To start a task:

request

HTTP GET request

/api/tasks.html?task=[task name]

If the rights are not sufficient or the specified task does not exists, the Web Server responds with a HTTP 404 status code (not found).

example

for hibernate

http://[user:password@]IP[:port]/api/tasks.html?task=Hibernate

internal task names[edit]

EPGStart Start EPG Scan

EPGStop Stop EPG Scan

Hibernate Hibernate

Standby Standby

Shutdown Shutdown

AutoTimer AutoTimer

CleanupDB Cleanup Recording DB

RefreshDB Refresh Recording DB

CleanupRefreshDB Cleanup and Refresh Recording DB

UpdateVideoDB Update Medias library DB

RebuildVideoDB Rebuild Video library DB

RebuildAudioDB Rebuild Audio library DB

RebuildPhotoDB Rebuild Photo library DB

ClearAudioStats Clear Audio library Stats

ClearRecordingStats Clear Recording Stats

ClearVideoStats Clear Video library Stats

ClearPhotoStats Clear Photo library Stats


control DVBViewer clients[edit]

client list[edit]

request

HTTP GET request

/api/dvbcommand.html

shows DVBViewer clients (pc names) which where connected to the RS sins the last RS restart.

request

HTTP GET request

/api/dvbcommand.html?target={pc name}

adds a PC to the list

send commands[edit]

request

HTTP GET request

/api/dvbcommand.html?target={pc name}&cmd={DVBViewer command line parameter}

Sends a command lineparameter to the DVBViewer client on the PC with the {pc name}

Make sure to encode special characters e.g. spaces in the command lineparameter properly for a URL.


deprecated functions[edit]

/api/status.html[edit]

(deprecated - please use status2.html)

http://[user:password@]IP[:port]/api/status.html

/tasks.html?task[edit]

(deprecated - please use /api/tasks.html)

http://[user:password@]IP[:port]/tasks.html?task=[task name]&aktion=tasks

/index.html?epg_clear=true[edit]

(deprecated - please use /api/epgclear.html)

http://[user:password@]IP[:port]/index.html?epg_clear=true

/api/getchannelsdat.html[edit]

(deprecated - please use /api/getconfigfile.html?file=channels.dat or /api/getchannelsxml.html)

http://[user:password@]IP[:port]/api/getchannelsdat.html

/api/getdiseqcxml.html[edit]

(deprecated - please use /api/getconfigfile.html?file=DiSEqC.xml)

http://[user:password@]IP[:port]/api/getdiseqcxml.html

/api/getfavourites.html[edit]

(deprecated - please use /api/getconfigfile.html?file=Favourites.xml or /api/getchannelsxml.html)

http://[user:password@]IP[:port]/api/getfavourites.html