Child pages
  • API01 RSS based API

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

...

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

Limiting Response Size
Anchor
nmc_rss_limiting_response_size
nmc_rss_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:

...

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.

...

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.

...

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

...

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.

...

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.

...

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:

...

Code Block
XML
XML
http://<RSS URL>?start=40&count=20 returns item 40 to 45

 

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.

Anchor
nmc_json_escaping
nmc_json_escaping
JSON Escaping

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

...

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

Code Block
http://127.0.0.1:9085/nmc/rss?fmt=json
No Format
{
   "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:

...

Code Block
{"description":"3 items" ,
"returneditems":"3 returned items" ,
"item": [
{"title":"Am I Evil?" ,
"enclosure": { "value":"" ,"type":"application/rss+xml" ,"url":"http://127.0.0.1:9000/nmc/rss/renderer/RBuuid%3A526F6B75-536F-756E-6442-000D4B3063D2/IBuuid%3A55076f6e-6b79-4d65-64ad-000129d7de2d,0%241%248I34826,0,0,Root,0,,1,0,Music,0%241,,6,0,All%20Tracks,0%241%248,,%7C4" } ,
"bookmark":"uuid%3A55076f6e-6b79-4d65-64ad-000129d7de2d,0%241%248I34826,0,0,Root,0,,1,0,Music,0%241,,6,0,All%20Tracks,0%241%248,,%7C4" ,
"meta": { "value":"" ,"id":"0$1$8I34826" ,"parentID":"0$1$8" ,
"restricted":"1" ,
"pv:supported":"true" ,
"pv:duration":"0:07:50" ,
"dc:title":"Am I Evil?" ,
"dc:date":"1998-01-01" ,
"upnp:genre":"Metal" ,
"upnp:album":"Garage Inc." ,
"upnp:originalTrackNumber":"17" ,
"dc:creator":"Metallica" ,
"upnp:albumArtURI":"http://192.168.17.1:9000/disk/O0$1$8I34826.jpg?scale=160x160" ,
"upnp:artist":"Metallica" ,
"pv:extension":"mp3" ,
"upnp:albumArtist":"Metallica" ,
"pv:rating":"1" ,
"pv:lastPlayedTime":"2010-07-16T12:07:07" ,
"pv:playcount":"8" ,
"pv:modificationTime":"1184772354" ,
"pv:addedTime":"1277751344" ,
"pv:lastUpdated":"1184772354" ,
"res": { "value":"http://192.168.17.1:9000/disk/DLNA-PNMP3-OP01-FLAGS01703000/O0$1$8I34826.mp3" ,
"duration":"0:07:50" ,
"size":"7602176" ,
"bitrate":"128" ,
"protocolInfo":"http-get:*:audio/mpeg:DLNA.ORG_PN=MP3;DLNA.ORG_OP=01;DLNA.ORG_FLAGS=01703000000000000000000000000000" } ,
"upnp:class":"object.item.audioItem.musicTrack"
}
}
,
{"title":"Breadfan" ,
"enclosure": { "value":"" ,"type":"application/rss+xml" ,"url":"http://127.0.0.1:9000/nmc/rss/renderer/RBuuid%3A526F6B75-536F-756E-6442-000D4B3063D2/IBuuid%3A55076f6e-6b79-4d65-64ad-000129d7de2d,0%241%248I35082,0,0,Root,0,,1,0,Music,0%241,,19,0,All%20Tracks,0%241%248,,%7C4" } ,
"bookmark":"uuid%3A55076f6e-6b79-4d65-64ad-000129d7de2d,0%241%248I35082,0,0,Root,0,,1,0,Music,0%241,,19,0,All%20Tracks,0%241%248,,%7C4" ,
"meta": { "value":"" ,"id":"0$1$8I35082" ,"parentID":"0$1$8" ,
"restricted":"1" ,
"pv:supported":"true" ,
"pv:duration":"0:05:41" ,
"dc:title":"Breadfan" ,
"dc:date":"1998-01-01" ,
"upnp:genre":"Metal" ,
"upnp:album":"Garage Inc." ,
"upnp:originalTrackNumber":"19" ,
"dc:creator":"Metallica" ,
"upnp:albumArtURI":"http://192.168.17.1:9000/disk/O0$1$8I35082.jpg?scale=160x160" ,
"upnp:artist":"Metallica" ,
"pv:extension":"mp3" ,
"upnp:albumArtist":"Metallica" ,
"pv:rating":"2" ,
"pv:modificationTime":"1184772354" ,
"pv:addedTime":"1277751344" ,
"pv:lastUpdated":"1184772354" ,
"res": { "value":"http://192.168.17.1:9000/disk/DLNA-PNMP3-OP01-FLAGS01703000/O0$1$8I35082.mp3" ,
"duration":"0:05:41" ,
"size":"5531648" ,
"bitrate":"128" ,
"protocolInfo":"http-get:*:audio/mpeg:DLNA.ORG_PN=MP3;DLNA.ORG_OP=01;DLNA.ORG_FLAGS=01703000000000000000000000000000" } ,
"upnp:class":"object.item.audioItem.musicTrack"
}
}
,
{"title":"Battery" ,
"enclosure":
{"value":"" ,"type":"application/rss+xml" ,
"url":"http://127.0.0.1:9000/nmc/rss/renderer/RBuuid%3A526F6B75-536F-756E-6442-000D4B3063D2/IBuuid%3A55076f6e-6b79-4d65-64ad-000129d7de2d,0%241%248I22282,0,0,Root,0,,1,0,Music,0%241,,14,0,All%20Tracks,0%241%248,,%7C4" \} ,
"bookmark":"uuid%3A55076f6e-6b79-4d65-64ad-000129d7de2d,0%241%248I22282,0,0,Root,0,,1,0,Music,0%241,,14,0,All%20Tracks,0%241%248,,%7C4" ,
"meta": {"value":"" ,"id":"0$1$8I22282" ,"parentID":"0$1$8" ,
"restricted":"1" ,
"pv:supported":"true" ,
"pv:duration":"0:05:10" ,
"dc:title":"Battery" ,
"dc:date":"1993-01-01" ,
"upnp:genre":"Other" ,
"upnp:album":"Basel, Switzerland (06-20-1993" ,
"dc:creator":"Metallica" ,
"upnp:artist":"Metallica" ,
"pv:extension":"mp3" ,
"upnp:albumArtist":"Metallica" ,
"pv:modificationTime":"1098714096" ,
"pv:addedTime":"1277751343" ,
"pv:lastUpdated":"1098714096" ,
"res": \{ "value":"http://192.168.17.1:9000/disk/DLNA-PNMP3-OP01-FLAGS01703000/O0$1$8I22282.mp3" ,
"duration":"0:05:10" ,
"size":"7438629" ,
"bitrate":"192" ,
"protocolInfo":"http-get:*:audio/mpeg:DLNA.ORG_PN=MP3;DLNA.ORG_OP=01;DLNA.ORG_FLAGS=01703000000000000000000000000000" } ,
"upnp:class":"object.item.audioItem.musicTrack"
}
}
,
]
}

Error Response

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

...

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.

...

No Format
nopaneltrue
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".

...