Child pages
  • API01 RSS based API
Skip to end of metadata
Go to start of metadata

Overview

The RSS module provides an API to browse all discovered servers, renderers and their associated play queues in the network. This RSS based API can be utilized to develop non-UPnP client devices within the home network, as well as remote clients, to access media servers and all their shared content and renderers, which can be monitored and controlled.

Accessing the root level

The root level is the highest level RSS feed container.

To access the root level, the URL is:

Client SDK:         http://127.0.0.1:9085/nmc/rss
Embedded in server: http://127.0.0.1:9000/nmc/rss

The following screen shows the root level of the RSS feeds.

Limiting Response Size

Since many of the responses to the API calls can be quite lengthy, there are two parameters that should be added to control the response size:

URL Query Parameter

What it does

start=

Controls which item returned as the first item in the RSS feed.

count=

Controls how many items are returned.

Server List

The server list is accessible via the following URL:

Client SDK:         http://127.0.0.1:9085/nmc/rss/server
Embedded in server: http://127.0.0.1:9000/nmc/rss/server

The following screen shows the list of the servers discovered:



The following is the listing (pretty-printed for readability) for the page above, containing the expected output for one server:


Header tags:

Tag

Description

<title>

Contains a description of the current list

<pubDate>

Current time and date

<description>

Total number of items available

<returneditems>

Number of items returned

<childCount>

Same as description but containing the number only

<id>

  • Server list: "Servers"
  • Renderer list: "Renderers"
  • RUI Server list: "RemoteUI Servers"
  • RUI Client list: "RemoteUI Clients"
  • Container: Object ID of container
  • Item: Object ID of parent container

<upnp:class>

UPnP class of current of current container. For generic containers such as server list "object.container".

<url>URL of the current view

Table 1: Description of header tags on an RSS feed

Server description tags:

Tag

Description

<item>

Specifies the sub category or the item itself.

<title>

Name of the device

<enclosure url=>

URL into the root directory of the server. The root bookmark (/RB) is the server ID.

<bookmark>

The bookmark pointing onto the server

<isOnline>

Since 7.2: true if device is online, false if offline.

If offline, then device info can be retrieved, but it cannot be browsed or searched.

<server>

The server container has the following tags.

<name>

Server name

<friendlyName>

Server name (UPnP style)

<manufacturer>

Name of the manufacturer.

<modelName>

Server model name.

<modelNumber>

Server version.

<modelDescription>

Server description.

<dlnaVersion>

DLNA version, typically DMS-1.50 or M-DMS-1.50

<upnpVersion>

UPnP AV version, typically 1.0

<playlistSupport>

true|false

This is set to true, if server supports these UPnP actions:

CreateObject, CreateReference, DestroyObject, UpdateObject

<isLocalDevice>

true|false

This is set to true, if device is local (means on same machine, not necessarily part of the process).

<isInternalDevice>

true|false

This is set to true, if device is in the same process, i.e. this is the server you got this response from.

<UDN>

The unique identifier for the device.

<baseURL>

The server's presentation page URL.

<multiUserSupport>

Gets information whether the media server has multi-user support enabled or not.

For Twonky Server 7.3 or later. For all other servers it is signalled as not being enabled.

<dtcpSupport>

Does the server generally support DTCP, ie. can it share content streamed via DTCP-IP?

<dtcpPushSupport>

Does server support DTCP push?

<dtcpCopySupport>

Does server support DTCP copy?

<dtcpMoveSupport>

Does server support DTCP move? If so, which formats?

<uploadSupportAV>

Does server support video upload?

<uploadSupportImage>

Does server support image upload?

<uploadSupportAudio>

Does server support audio upload?

<knownServer>

The type of server that is recognized.

If this is provided, then a list of well-known bookmarks is available for this server
(see wellknownBookmark).

<wellKnownBookmark>

A list of well-known bookmarks supported on this server.
These bookmarks can be used to browse specific containers with certain known IDs.

Please note that these IDs are not necessarily those returned in browse responses.
Initially the client tries to retrieve the real IDs if these are not fixed.
If known, then this tag has an attribute realContainerId listing the actual object ID.

<upnp:class>

UPnP object type, for servers always object.container.

Table 2: Description of server root item tags on an RSS feed container

Server Content

Every item contains the URL of the item in the enclosure tag. By using this it is possible to traverse the navigation tree of the server.

Warning: Always use paged browsing to list server content (see section Limiting Response Size above). Especially when browsing the All folders the number of items can easily exceed ten thousand items. Querying them all at once takes first a long time and second can lead to out of memory conditions. Hence, it is strongly recommended to use a paged browsing with some additional loading of additional pages in the background.

The next screen shows the root level of a Twonky Server.



The source for the server root level is:



The item tags have the following meaning:

Tag

Description

<item>

Specifies the sub category or the item itself.

<title>

Name of the sub container.

<enclosure url=>

URL of an item. The root bookmark is the server.The item bookmark is set to traverse through the navigation tree of the server.

<container><meta>

Containers generate RSS Feeds based on the object classes of their contents.
The <meta> tags can contain quite a variety of information returned by the server.

Table 3: Description of item tags on an RSS feed container

The structure of the RSS feeds is described in more detail in section 7.2.1 of the TwonkyServer 6.0 "Technical Specification and APIs" and the usage of RSS feeds is described in section 7.2.2 of that document.

Parent List

As you navigate into the Music, Photo, Video, or other subcontainers of the server, a list of parent containers and links will be provided at the end of the RSS output. The list proceeds from most-specific (deepest) to least specific (topmost) containers. This information will look like the following:

Tag

Description

<id>

Container ID of the parent item

<title>

Name of the container

<url>

URL of the container

Sorting

By appending the sort or the try_sort parameter it can be requested that the server returns the items in a specific sort order.
The actual sorting happens on server side and it also depends on the server, which sort options are available.

The difference between both parameters is that sort will return an error if the server fails with that sort option whereas try_sort will reset to the server default sort-order and return that response instead.

The sort parameter takes a comma-separated list of sort options of this type:

Example:

The example shows that the "All Videos" container shall be listed with title descending and and creator ascending.
Current known sort options are:

  • title
  • creator
  • genre
  • album
  • artist

It is also possible to directly provide the UPnP names.
Example:

Note: Either use the first or the second option. When both schemes are provided, then all options using the UPnP naming scheme are ignored.

Renderer List

The renderer list is accessible via the link on the root page. The URL is

.



The source for the renderer list is:



The root renderer list constructs the header part that is color-coded as light blue and the item tags those are color coded as light green.
Between items are set new line so it would be easier to follow the items.

Tags are:

Tag

Description

<channel>

Channel (metadata) and its contents

<title>

Contains a description of the media Container.

<pubDate>

Date and time when response was being created

<description>

Tells how many sub categories are found.

<returneditems>

Same as above.

Table 4: Description of renderer header tag on an RSS feed.

The item tags have the following meaning:

Tag

Description

<item>

Specifies the sub category or the item itself.

<title>

Name of the sub container.

<enclosure url>

URL of a root item. The root bookmark (/RB) is the server ID.

<isOnline>

Since 7.2: true if device is online, false if offline.

If offline, then device info can be retrieved, but it cannot be controlled.

<renderer>

The renderer container has the following items.

<name>

Renderer name

<friendlyName>

Renderer name (UPnP style)

<manufacturer>

Name of the manufacturer.

<modelName>

Renderer model name.

<modelNumber>

Renderer version.

<modelDescription>

Renderer description.

<dlnaVersion>

DLNA version, typically DMR-1.50/-1.51 or M-DMR-1.50/-1.51

<upnpVersion>

UPnP AV version, typically 1.0

<isLocalDevice>

true|false

This is set to true, if device is local (means on same machine, not necessarily part of the process).

See note below.

<isInternalDevice>

true|false

This is set to true, if device is in the same process, ie. an LDMR.

See note below.

<baseURL>

Presentation page

<TrackURI>

URI of current track

<TrackMetaData>

Metadata of current track

Table 5: Description of renderer root item tags on an RSS feed container

Note:

For protocol adaptation LDMRs (embedded DMR) such as Apple TV and Roku the tags reveal an internal but not local device as these LDMRs actually control remote devices.

Renderer Queue

Every renderer item contains the URL of the renderer queue in the enclosure tag to retrieve the items listed in the renderer queue.

The renderer queue is located below the rendererlist by appending /RB<renderer bookmark>.

Example: http://127.0.0.1:9085/nmc/rss/RBuuid%3A56066f6e-6b79-1d65-a45b-842b2ba75e4c

Warning: Always use paged browsing to list a renderer queue (see section Limiting Response Size above). The number of items added by the user can easily exceed ten thousand items. Querying them all at once takes first a long time and second can lead to out of memory conditions. Hence, it is strongly recommended to use a paged browsing with some additional loading of additional pages in the background.

The next screen shows the queue of the Soundbridge.



The source for the renderer queue is:



Tags are:

Tag

Description

<?xml version="1.0" encoding="utf-8"?>

Specifies the xml version and encoding

<rss version="2.0"

Version of RSS with the media parser with the xmlns Media Feature Tag.

<channel>

Channel (metadata) and its contents

<title>

Contains a description of the media Container.

<link>

A link to the RSS feed containing the media Container contents.

<pubDate>

Renderer startup time.

<description>

Tells how many sub categories are found.

<returneditems>

Same as above.

<language>

The language channel is written in.

<copyright>

Copyright notice for content in a channel.

Table 6: Description of renderer queue tag on an RSS feed.

The item tags have the following meaning:

Tag

Description

<item>

Specifies the sub category or the item itself.

<title>

Name of the sub container.

<enclosure url

URL of the item in the queue. The URL contains the renderer bookmark (/RB) and the item bookmark (/IB).

<bookmark>

The item bookmark.

<meta>

Containers generate RSS Feeds based on the object classes of their contents.

Table 7: Description of renderer queue item tags on an RSS feed container

Specifying Start, Count and Format

Parameters can be added at the end of each URL with a question mark "?" followed by the parameter keyword and the value. Further parameters are separated by an ampersand '&'. The parameters are:

 



Every call to such an RSS-URL returns a list of items. This list can be empty, has one or many items. The parameter 'start' defines the index of the first returned item and the parameter 'count' defines the number of items returned.
Example: The RSS URL (http://<RSS URL>) returns 45 items. The items should be placed on three pages, each page has place for 20 items. The parameters of each page are:

Page 1:


Page 2:


Page 3:

 

JSON Formatted Data

The parameter 'fmt=json' returns the HTTP request in the format JSON (JavaScript Object Notation). JSON is a text format that is language independent.

JSON Escaping

NOTE: Starting with version Twonky 8.1 are all JSON values by default XML escaped!

The XML escaping of the JSON feed returned by /nmc/rss?fmt=json and /nmc/rpc?fmt=json can be used if a web UI directly injects the returned values into HTML pages.

Example for disabled escaping:

{"title":"abc<script>alert('title')<\/script>def"}

Example for enabled escaping (default):

{"title":"abc&lt;script&gt;alert(&apos;title&apos;)&lt;\/script&gt;def"}

This setting affects all RPC and RSS results with JSON support. It does not affect any functions or non-JSON results.

The configuration can be configured in two ways:

  1. Ini property escape_json / INI_ESCAPE_JSON
    This property can have values 0 (no escaping) and 1 (escaping). Default is 1.
    Note: This property is part of the blacklist which means it cannot be changed during run-time but only via the ini-file or command-line.
  2. C-API function tm_nmc_rpc_set_json_escape()
    This toggles the setting during run-time and takes as parameter value either TRUE to enable escaping and FALSE to disable it.

As the escaping is security relevant (as can be seen from the example above), there is no RPC to change the setting.

JSON Root Level

{
   "id":"NMC-Root",
   "title":"NMC-Root",
   "upnp:class":"object.container",
   "url":"http://127.0.0.1:9085/nmc/rss?fmt=json",
   "description":"2 objects available in container",
   "returneditems":"2 objects returned from container",
   "item":[
      {
         "title":"server",
         "enclosure":{
            "value":"",
            "type":"application/rss+xml",
            "url":"http://127.0.0.1:9085/nmc/rss/server"
         },
         "upnp:class":"object.container"
      },
      {
         "title":"renderer",
         "enclosure":{
            "value":"",
            "type":"application/rss+xml",
            "url":"http://127.0.0.1:9085/nmc/rss/renderer"
         },
         "upnp:class":"object.container"
      }
   ]
}

JSON Renderer Queue

The URL of the renderer queue in the chapter above with the parameter 'fmt=json' is:


The source of the renderer queue in JSON-format is:

Error Response

If an error happens during the RSS invocation, then a JSON object in this format is returned:

{"success": "false", "code": "<number>", "message": "<reason>"}

For example:

{"success": "false", "code": "3", "message": "Specified device does not exist"}

For a list of error codes see section Response Messages and Codes in the RPC chapter.

Twonky server URL options

Parameter "download=1" can be added to URL of content shared by Twonky server.

Twonky will change content mimetype to "application/octet-stream" and add extra line to HTTP response header like this:

"Content-Disposition: attachment; filename=content_filename.ext"

This feature can be used to make browser show the "Save As" dialog box once a content link is clicked.

 

Example:

Requested URL:

http://192.168.0.1:9000/disk/DLNA-PNMP3-OP01-FLAGS01700000/O0$1$8I273.mp3?download=1

Response HTTP header

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 3515724
Date: Mon, 26 Jan 2015 09:14:10 GMT
Last-Modified: Wed, 07 Jan 2015 11:39:43 GMT
Accept-Ranges: bytes   Connection: close
Content-Disposition: attachment; filename="01-Watermark.mp3"
transferMode.dlna.org: Streaming
EXT:
Server: Windows NT/5.0, UPnP/1.0, pvConnect UPnP SDK/1.0,  Twonky UPnP SDK/1.1 

Requesting Metadata with Specific Adaptation

Twonky Server as well as Twonky SDK have support for client adaptations by the provided "Device Database".

The database resides in the directory "resources/devicedb" and contains adaptations for a large set of devices. The adaptations vary from dealing when beaming to specific renderers, over letting Twonky Server pretending being a different server to modyfying the metadata for certain clients.

For RSS the latter category is relevant as it may return the metadata with adaptations such as

  • adapted and/or suppressed MIME types in resources
  • specific flags to be added
  • images, album art and thumbnails returned in certain resolutions
  • etc.

By default the RSS server feed as well as RPC search results return all available metadata.

An application may override this per request by adding the X-PV-CLIENTNAME header entry. The syntax is:

X-PV-CLIENTNAME: <display name of device db entry>

If this is not provided, then the one in resources/devicedb/PacketVideo/Twonky_NMC_WebAPI.xml is used. If you look into the XML, then you find in it:

<DisplayName>myTwonky</DisplayName>

So specifying nothing is as if a request contains this header line:

X-PV-CLIENTNAME: myTwonky

You can use now the display name of any entry or add your own device db entry and use that name.

WARNING: In case you add your own device db entry:

  • avoid a duplicate display name as this the key for the db, a second entry will be ignored
  • if your adaptation is supposed to work also with Twonky Servers on other devices, please provide it back to PacketVideo to be incorporated in the regular release


This header entry is taken into account since version 8.1 and takes effect when browsing and searching Twonky Servers since version 7.2.

  • No labels