Introduction

An application using the REST APIs can implement any kind of home network audio, video or image control functionality, from a generic AV controller application to a dedicated picture slideshow controller that allows watching photos on your TV set, controlled from a mobile phone. These APIs allow controlling the Twonky DLNA stack through a set of REST calls and retrieve metadata in RSS or JSON format.

The Twonky DLNA stack implements the UPnP AV Control Point (CP) and DLNA Digital Media Controller (DMC). This includes the media server control point (MSCP) and media renderer control point (MRCP) functionality as well as DLNA upload and download controller. This functionality allows to control UPnP and DLNA based home network media servers like Twonky Server and Microsoft Windows Media Player Sharing as well as any UPnP AV and DLNA based media renderer devices.

This document is the technical specification of these REST APIs. It assumes the reader is familiar with related web technologies and standards, as well as with the basics of UPnP and DLNA home network technology. Some features of the REST APIs are only available in case the client is integrated with a DTCP-IP enabled Twonky Server.

Use Cases

The REST APIs enable the implementation of a DLNA control point and DLNA player without the need for a DLNA stack. The API supports discovery and controlling of media servers and media renderers in the home network, as well as the DLNA upload (UP) and download (DN). The media server control API supports browse, search and sort, as well as storage and retrieval of server side WPL playlists. The DLNA push controller feature allows selecting media items on a media server, adding them to a play queue and sending them to DLNA renderers in the home network.

Concepts

Media content on a media server can come with a huge list of associated metadata. To easily reference a specific media content item on a media server (or in a play queue) the client uses bookmarks. Bookmarks are the recommended way to reference and exchange position information and media items within the application. Bookmarks are NOT persistent and only designed for short-term use within the APIs. So an application can request a bookmark for a specific media item on a media server and tell the client to add this item to a play queue without the need to handle any actual metadata for this item. Bookmarks are basically strings but are opaque and shall not be manipulated by applications in any form.

All API calls are blocking calls. They only return after the request was completed. For all calls involving network access this can take relatively long time, several seconds are possible for a busy media server. Worst case is a time out (e.g. the target device is dead), taking up to a minute. Depending on the type of application this can create serious issues. If it's a headless application performing some background action, it might be irrelevant. For all UI-based applications this means most calls to the APIs need to be decoupled from the UI threads. A typical implementation would provide a request queue with callbacks on completion of the call. The application would implement some state machine on top of this, for example to show a spinning wheel while the request is being processed and allow to simply aborting it. Or in a UI automatically abort the request if the user selects to do something else.

By using the API a play queue for each media renderer in the network is automatically created. By using the bookmarks an application can add media items to a queue in one simple step without the need to handle a set of metadata. It's also possible to add media items to a play queue by setting all required metadata directly.

Control point design considerations

The REST APIs provide a powerful interface to browse and search media servers, and control media renderers in a home network and provide a robust way to render playlists on media renderers automatically. It abstracts much of the complexity of network access and network device control from the application development. Nonetheless the controlled devices are only accessible through a network and the application design has to take this into account. Also, it is important to collect experience with networked device control, especially UPnP & DLNA control points, media servers and media renderers, before designing the application.

Response times of network-controlled devices can pose serious issues for an application. It is strongly recommended not to couple UI implementation and web API requests directly. A good application design should be prepared to handle response times of up to several seconds. The typical design for an application accessing the REST API will provide a multi-threaded request queue to e.g. load a media server directory and provide state machines for media renderer control, to prevent the application from blocking and to allow a user to keep interacting with the application.

Another important design consideration is the amount of metadata involved. Media servers can easily have directories with more than 10000 items. For most applications, especially on mobile and embedded devices, it's impossible to store the related metadata in memory (e.g. in a list box). In addition, the loading time for all the data would be unacceptable for a user trying to interact with the application. Therefore the application design should allow to only load the small number of visible items in a list view, plus possibly a cache for next few items to allow smooth scrolling. Loading this data should be done through the above mentioned multi-threaded request queue. The application should show some intermediate text or feedback to the user when scrolling, or jumping, too fast (e.g. each line shows „...") and then refresh the displayed text or graphic as soon as the request queue has processed and the respective media item has been loaded. Invisible items in the list view should release their (test) data to recover memory. This could be done by a background thread that's checking for text items out of the currently visible windows of items.

REST API

The REST API consists of two modules that enable developers to utilize the underlying DLNA stack through standard HTTP requests. One module provides the functionality to browse servers and renderers and the according queues (available at http://..../nmc/rss). The data is returned either as RSS XML or as JSON. The second module enables the developer to utilize the APIs to select and control renderers and to manage the play queues. This module (available at http://..../nmc/rpc) exposes the APIs via HTTP GET requests and a specific syntax in the URLs.

Together with Twonky Server an example web-based JavaScript user interface implementation is provided (available at http://..../nmc/web), which should be used as a reference for the correct usage of the API. The web UI of Twonky Server itself contains a control point fully based on these interfaces and is hence the best example how to interact with them.

Access Restrictions

Access to the REST API can be configured with the INI property enablenmcwebapi.

Possible values:

0: disabled
1: enabled (default)
2: local access only (from 8.1.2 on)

Note: Since 8.1.2 this property cannot be changed during run-time using an HTTP RPC call anymore. The INI file or command-line arguments are expected to contain the correct value at startup of Twonky Servers or client.

The property can be changed at any time via NMC IOCTL NMC_IOCTL_SET_INI_PROPERTY / "SetIniProperty" and takes effect immediately unless the initial value was 0. In this case the property can be changed, but has no effect as the according handlers are not available.

RSS

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

.

worddav7308ccfb2a9ad653516936f20af4ac4c.png [imported from a Word document]

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.

worddav888f89af67258e572298898b01ba632e.png [imported from a Word document]

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:

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.
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.

RPC

Call Syntax

The REST control API is used to control and manage servers and renderers, with the bulk of the calls being for the renderer.

The syntax of the call is:

The syntax for two parameters is:

In case the client is not part of the server, the default port is 9085.

Response Template

The general form of the RPC response will look something like the following.

The three JSON object properties are:

Property	Meaning
success	Can be true or false.
code	Can be one of the standard HTTP Response Codes.
message	Can be a textual description of what occurred or the information that was requested.

Response Messages and Codes

General rules (with a few exceptions) for error codes:

Negative error codes are generated by the RPC module
Error codes zero and below hundred are generated by the Twonky stack.
Error codes hundred and above are sent by the UPnP device.

Code	Message
-11	Download already in progress, cannot start another
-10	Upload already in progress, cannot start another
-9	Search failed
-8	Internal error
-5	Execution of the action failed
-4	Bookmark not found
-3	Error on deleting the context
-2	Error on creating a context
-1	Invalid args given for this NMC RPC call
0	Call succeeded
1	Target index does not exist
2	Parameter missing or invalid
3	Specified device does not exist
4	Known device that is currently not accessible
5	Specified device does not exist
6	Failed to connect to device
7	Invalid response from device
8	Out of memory
9	Query led to no result
10	Result does not fit into provided buffer
11	System is being shutdown, function aborted
12	Target already exists
13	Function / service not implemented
14	Local function failed for unknown reason
20	User aborted operation
21	Control Point rejected invocation, since this action is known to be broken
22	Resource could not be added due to limited space eg in an array
23	Connection was unexpectly closed or lost.
24	Could not get upload response code - success/failure of upload is unknown
25	Play queue is empty or contains only unsupported objects
26	Context Ambiguity found after network call
27	Timeout
28	Operation cancelled
29	Metadata not available
30	Browsing led to recursion
50	DTCP Move failed
51	DTCP Move receive failed
52	DTCP Move commit failed
53	Invalid DTCP Move resource
54	Not enough disk space to perform DTCP Move
55	Not supported content type for DTCP Move
56	Cannot create file system objects
57	Invalid DTCP Move target file name
58	Invalid DTCP Move session
200	HTTP request succeeded
401	Invalid SOAP Action
402	SOAP request with invalid arguments
412	State does not allow this type of request
500	Unknown internal device error
501	Action failed for unknown reason
600	Argument value invalid
601	Argument value out of range
602	Optional action not implemented
603	Out of memory
701	State does not allow requested action, Server does not find specified object, or Invalid Name. See UPNP RendernerControl Doc: 2.4.2.3. Errors
702	Update of object failed due to invalid supplied current value, or No content to be played
703	Update of object failed due to invalid new value, or Error reading media
704	Missing parameter, Unsupported playback format, or Recording Item doesn't exist
705	Property is read-only (DMS response), or Blocked by other CP or direct control (DMR response)
706	Parameters do not match
708	Unsupported or invalid search criteria
709	Unsupported or invalid sort criteria
710	Device does not support requested seek mode, or Server does not find specified container
711	Object is read-only (DMS response), or Cannot seek to requested track or position (DMR response)
712	Wrong metadata for object, or Play mode not supported
713	Parent directory of object is read-only
714	MIME type not supported
715	Resource access denied
716	The specified resource was not found
717	Play speed not supported
718	InstanceID not supported in AVTS (different for RCS)
801	No permission to access server/service

JSON Format

Where noted RPCs support as return value the JSON format by appending "fmt=json" to the URL.

See also JSON escaping for a discussion of the escaping of JSON values.

Available RPCs

Function

Parameter

Description

add_bookmark

renderer=[BOOKMARK]
item=[BOOKMARK]
index=[value]

Adds an item to the renderer queue at the position "index".
If no "index" parameter is provided, then the item will be added to the end of the queue.

add_metadata

renderer=[BOOKMARK]
metadata=[data]
url=[url]
index=[value]

alternatively to metadata the next fields can be used:

title=[value]
artist=[value]
album=[value]
genre=[value]
albumArtURI=[value]
duration= [value]

creator=[value]

addlHdrs=[value]

Adds an item to the renderer queue at the position "index".
If no "index" parameter is provided, then the item will be added to the end of the queue.

Please keep in mind that if this RPC is called asynchronously by multiple callers, the queueing order may be different than expected.

Instead of specifing metadata as a complete XML one can provide it as a set of fileds. In this case omit metadata parameter and make sure that you provided title parameter. Other metadata fields are optional.

If a local Twonky Server is running, then <url> may be a file URL, e.g.:

http://127.0.0.1:9085/nmc/rpc/add_metadata?renderer=uuid:07c8fc00-f5ff-43e0-9e67-0e9b330f8f0f&url=file:///share/videos/video.mp4

The RPC will contact the server for the corresponding bookmark and will then behave like RPC add_bookmark.
Note that in this case any metadata parameters are ignored.

<addlHdrs> (since 7.1.2):

Users of this API can pass "addlHdrs=<url_encoded_string>" which will then be passed to the Twonky ProxyServer to assist it in creating the metadata.
Additional headers to be added should be of the form:
addlHdrs=url.encode(X-TWONKY-PARAM: <param1>: <value1>\r\nX-TWONKY-PARAM: <param2>: <value2>\r\n)

Note that we do need the "\r\n" because these strings will be added as http headers as is. The "\r\n" would have to be encoded as "%0D%0A".

Starting with version 8.0 the parameter privateBM is ignored and the url parameter is also used as bookmark.

As of Twonky Server 8.1.1 Twonky ProxyServer is by default no longer part of the server and only available upon request.

beam

renderer=[index]
url=[url]

Beams the specified URL to the specified renderer.

can_play

renderer=[BOOKMARK]
item=[BOOKMARK|URL|TYPE]

Queries whether the specified renderer supports the according item. The item parameter can have one of these types:

a bookmark of an item to check if the according item is supported
a complete protocol info such as "http-get:*:audio/mpeg:DLNA.ORG_PN=mp3"
a MIME type such as "audio/mpeg"
a URL pointing directly to a media item (this is neither resolved or followed)

Returns the string 1, if the renderer does not support the item, the string 0, if the renderer supports it..

check_multiuser_access

server=<bookmark>

user=<username>

password=<password>

Checks whether the specified user has access to the server.

Returns a JSON object containing the result:

{ "success" : "false" |" true" , "code" : "error code", "message" : "reason" }

The following error codes are common:

0: Access is granted (user is known)
801: Access is denied (invalid credentials, server does not support multi-user)
-1: Invalid arguments to RPC
1 and 3: Invalid device
7: Response from server was invalid
14: Could not contact server (no TLS, network issue)

The value of "success" is only true for error code 0, ie. when access is granted.

Note:

It is recommended that the multi user API is only used if the server metadata contains element "multiUserSupport" with value "true".

This is currently only supported for Twonky Server 7.3.

If the selected server is not in the same process, then the communication is done via https to hide the user credentials.

It is also recommended to use https when invoking this RPC.

Since 7.3

clear

renderer=[BOOKMARK]

Clears the renderer queue.

delete_item

renderer=[BOOKMARK]
index=[value]

Deletes an item from the renderer queue.

download

bookmark=[BOOKMARK]
operation=[start | stop | getstatus]
filename=[path]

[fmt=json]

Downloads the specified bookmarked item. Operation parameter can start, stop, and get status of transfer. Filename parameter specifies the name of the file, however any path information provided here will be discarded and the file will ultimately be placed in the temporary directory used by the Client SDK or Twonky Server. This is "<appdata>/temp" (appdata as specified in the ini file).

If JSON output format requested, it will looks like this

{"result": "ok", "path":"<path to temp folder>/<filename>"}

dtcp_content_upload
This functionality is only available for specific configurations of the Client SDK.
Please see „2.4 DTCP Support" for further details.

operation=[start | stop | getstatus]
src=[BOOKMARK]
dst=[BOOKMARK]

Controls a DTCP transfer between a source server and a destination server. Both servers must support DTCP.

dtcp_content_download

This functionality is only available for specific configurations of the Client SDK.
Please see „2.4 DTCP Support" for further details.

operation=[enabled | start | stop | finish| getstatus]
file=[BOOKMARK]

Controls DTCP-IP content download from the source server and the current server. Both servers must support DTCP.

dtcp_get_capabilities ¹

src=[BOOKMARK]

Returns the DTCP capability list of the specified server.
See tag description dlna:X_DLNACAP in chapter DTCP Support for the strings that can be returned.

get_albumart

renderer=[BOOKMARK]
or
renderer=[BOOKMARK]&index=[queue-index|bookmark]
or
server=[BOOKMARK]

Optional parameters:

max_edge=num_pixel
default: 256
mime_type=type
default: image/jpeg
ignore_default=0|1
default: 0
scale=WxH
device=0|1
default: 0

This function can be used to get the album art from these sources:

from the metadata of the renderer of the currently playing item
from the queue item specified by index or bookmark
from the server using the specified item bookmark
device icons for a server or renderer

The optional parameters can be used for these purposes:

Specifying the maximum resolution of the album art. The call will only return album art with width and height below or equal to that size in pixel.
Specifying the content type the album art shall have (typically image/jpeg or image/png).
If ignore_default is set to 1, then album art delivered by Twonky server 5 or later that is detected as being the default album art will be ignored and an error will be returned. For all other servers is this setting ignored.
Specifies a specific size for the image. If the server supports scaling, then the URL is accordingly modified. Format is "WxH". Both need to be equal to or smaller than max_edge. The returned image might be smaller to keep the aspect ratio of the thumbnail. If not supported by the server, then the non-scaled version is returned instead.
If not specified, then the unscaled version is returned.
If device is set to 1 then the device icon for the specified renderer or server will be returned

The call returns the URL that fits best the parameters or an error, if these requirements cannot be met. The call works for album art of music and video items as well as thumbnails of image items.

get_current_playspeeds

renderer=<BOOKMARK>

Optional parameter:

fmt=json

Returns the currently supported playspeeds from the renderer with the specified bookmark.

The according playspeeds are those announced in DLNA style in the CurrentTransportActions and are not taken from the AVTS service description.

In opposite to the DLNA specification contains this list always the value 1 to offer a complete list. If the renderer does not support or announce playspeed, then only the value 1 is returned.

In none-JSON format multiple values are separated by the pipe symbol.

Examples:

RSS: -4|-2|-1|-1/2|1/2|1|2|4
JSON: {"PlaySpeeds": ["-4", "-2", "-1", "-1/2", "1/2", "1", "2", "4"]}

Since 7.2.6

get_events

eventid=[last event ID]

Returns a list of server and renderer events separated by new line character "\r\n"

Result format: [event ID] "server"/"renderer" [event type] "bm="[BOOKMARK] "meta="[METADATA]

event ID: monotonically increasing integer signifying event ID

"server" / "renderer": string representing source of event

event type: integer signifying the type of event

"bm="[BOOKMARK]: bookmark of server/renderer

"meta=[METADATA]: any metadata. Currently used to provide container object id/bookmark in case of container update events if configured.

RPC returns current event ID as result if e.g. no event has yet recorded, state is same as requested event ID.

Note:

By default container update is disabled. To enable it IOCTL "SetContainerIDEvtMode" has to be invoked with one of these configuration parameters

"PASSTHROUGH" which returns comma separated list of updated container object IDs

"REPORT_EACH_ID" which returns each container object ID via separate container update events

"REPORT_BOOKMARK_ID" which returns each container bookmark via separate container update events

Updated Since 8.1

get_item_path

server=[BOOKMARK]

Optional parameters:

fmt=json

Gets from a local Twonky server the file path for an item referenced by the specified bookmark.

The function will return an error for remote servers or if the bookmark does not refer to a local item. The path of containers is not available.

The function returns a string containing an OS specific file path, not a file URL. If parameter "fmt=json" is provided, then the return format is the following:
{"path": ["<path>"]}

Note: Requires Twonky server 7.1 or later.

Example:
get_item_path?server=uuid:...&fmt=json
{"path": ["C:\Users\Public\Music\My Music.mp3"]}

get_known_bookmark_mapping

server=[BOOKMARK]

Returns a JSON object containing the mapping between well-known bookmarks such as ".,music" or ".,video/all", etc., and the container ID that represents them on the server.

get_mute

renderer=[BOOKMARK]

Returns the mute state.0 = off1 = on

get_nmc_version

Returns the current version of the Client SDK / Twonky Server as string (e.g. 7.2)

get_playindex

renderer=[BOOKMARK]

or

renderer=[BOOKMARK]&getIsPlayIndexValid=1

Returns the string [playindex] | [remaining]

Returns the string [playindex] | [remaining]|[OK/NA]

get_playmode

renderer=<BOOKMARK>

Optional parameters:

fmt=json

Retrieve the current play mode of the renderer.

See RPC play for a description of available modes.
Note: keep setup flag is not returned for this RPC as it makes no sense.

Return value:

Normal: Only the value is returned, eg. 0

JSON: {"mode": "<value>"}

The RPC is available since version 7.3.1.

get_playspeed

renderer=<BOOKMARK>

Returns the current playspeed of the specified renderer.

Controlling HTTP Response Codes

During development of the RPC handler, it was discovered that sending HTTP Response Codes other than "200 OK" was problematic when using JSONP to handle the returning data. By default, the RPC calls will return "200 OK" as the HTTP Response Code.

Setting the useRealHttpCode to true causes the true HTTP Response Code to be returned, so this value could be something other than "200 OK".

Examples

To illustrate the RPC functions here are some examples:

Retrieving A Renderer Bookmark

In order to control a renderer, the API user needs to retrieve a bookmark for it first. The bookmark serves as a unique identifier for the renderer to be controlled. To do this information, an RSS feed needs to be retrieved. RSS feeds and format are fully described in the RSS documentation.

Here is a sample entry from the renderer RSS feed:

The renderer bookmark, which needs to be passed to all of the renderer RPCs, is the string contained in the <bookmark> tag.

Retrieving An Item Bookmark

Using the RSS feeds, the API will return item information using the following form:

Checking If A Renderer Can Play An Item (can_play)

A song shall be added to the queue of a Roku SoundBridge.
The bookmark to the song is verified with the web API to check if the SoundBridge supports the media format.

Syntax:

URL:

Function returns:

The SoundBridge can play the song.

Adding A Bookmark To A Renderer Queue (add_bookmark)

The song is added to the queue of the SoundBridge.

Syntax:

URL:

Function returns:

The song was added successfully.

Adding An Item Using A URL To A Renderer Queue (add_metadata)

A different song is added to the queue of the SoundBridge.

The metadata= parameter of the add_metadata method uses URL-encoded XML information in one of the following forms to add an item to the queue:

A Full DIDL-Lite XML response from a BrowseMetadata SOAP call

Part of a Full DIDL-Lite XML response

An RSS <meta> XML element (Music)

An RSS <meta> XML element (Photo)

An RSS <meta> XML element (Video)

Syntax:

URL:

Function returns:

The song was added successfully.

Adding An Unsupported Item To A Renderer Queue

A picture shall be added to the queue. Since the SoundBridge is a music player and cannot show pictures, the call will return an error message.

Syntax:

URL:

Function returns:

A second song is added to the end of the queue of the SoundBridge

Syntax:

URL:

Function returns:

The second song shall be made the first item in the queue

Syntax:

URL:

Function returns:

Play the songs in the queue.

Syntax:

URL:

Function returns:

Get the play state.

Syntax:

URL:

Function returns:

State is 1, that means the song is playing. The current position is 0:03:08 and the duration of the song is 0:04:39.

Get all server and renderer events.

Syntax:

URL:

Function returns:

The returned string in a more readable format:

Event ID	server/renderer	Code	Bookmark
1	server	4	uuid:55076f6e-6b79-4d65-646d-000129d7de2d,0
2	server	1	uuid:55076f6e-6b79-4d65-646d-000129d7de2d,0
3	server	1	uuid:55076f6e-6b79-4d65-646d-000129d7de2d,0
4	renderer	16386	uuid:526F6B75-536F-756E-6442-000D4B3063D2

Server and renderer events

Server codes	What they mean
1	server updated
2	lost connection to server
4	server detected

Renderer codes	What they mean
0x4001 (16385)	lost contact to renderer
0x4002 (16386)	renderer detected

Error return codes

invalid args given for this rpc call
error on creating a context
error on deleting the context
bookmark not found
execution of the action failed
unknown error

Logging source and level

The log source specifies the module that should be logged. It is an OR'ed combination of these values:

Logging Sources

Source number	Source name
1	Common system messages
2	Device discovery (generates lots of output!)
8	HTTP communication
32	Device events and subscription messages
64	Queue handler communication
128	High level API
4096	DTCP-IP

The log source could now be set to 1+8+32=41 to enable logging for system, http and event messages. The default is zero which means logging is disabled. Other values are used by Twonky server and are ignored by the client.

Logging Levels

Level number	Level name
1	Trace
2	Info
3	Warning
4	Error
5	Critical

A lower number includes logs for all higher numbers. The lower the number the more is logged.
Default is 4.

Example: A value of 9 for source and 2 for level enables info, warning, error and critical logs for the system and HTTP modules.

Search Syntax

General Search Syntax

http://127.0.0.1:9000/nmc/rpc/search?server=[BOOKMARK]search=[hex-encoded query]start=[value]count=[value]

Performs a search for the specified query. The search parameter is better described below.
Note: The search query must be hex-encoded. For paging through a search, the start and count parameters can be used.

The search syntax takes two forms.

One can use the UPnP search syntax:
upnp:class derivedfrom "object.item.audioItem.musicTrack" and (dc:title contains "FindThis" or upnp:genre contains "FindThis" or upnp:artist contains "FindThis")

Once hex-encoded, this can be used with a search RPC call as follows:

http://127.0.0.1:9000/nmc/rpc/search?server=uuid%3A4f1bf61c-599b-443d-b41d-36408362ec75,0&search=75706e703a636c617373206465726976656466726f6d20226f626a6563742e6974656d2e617564696f4974656d2e6d75736963547261636b2220616e64202864633a7469746c6520636f6e7461696e73202246696e645468697322206f722075706e703a67656e726520636f6e7461696e73202246696e645468697322206f722075706e703a61727469737420636f6e7461696e73202246696e64546869732229&start=0&count=10

One can also use a simplified search syntax:
type=musicItem&artist=FindThis&album=FindThat

This also must be hex-encoded if used in the RPC, and would look like:

http://127.0.0.1:9000/nmc/rpc/search?server=uuid%3A4f1bf61c-599b-443d-b41d-36408362ec75,0&search=747970653d6d757369634974656d266172746973743d46696e645468697326616c62756d3d46696e6454686174&start=0&count=10

Simplified Search Syntax

The simpler search syntax is presented below and uses URL-encoded parameters to set up the search. Caveat: These search tokens are combined into an AND search, e.g. a searched-for item must have all of the token values in its metadata before it matches. There is currently no provision for OR searches.

By default, these searches will use the 'contains' search semantic, meaning that they will match substrings in the metadata. e.g. 'title=FindThis' will match when a title is 'FindThisThing'.
To force an exact, whole-word match of a metadata string, append the 'exact=1' parameter somewhere in the search string. e.g. 'title=FindThis&exact=1' will not match when a title is 'FindThisThing'.

It will only match when a title is 'FindThis'.

The following parameters are allowed in a URL-encoded query string format.

keyword - value
title - the title
creator - the creator
genre - the genre
album - the album
description - description
date - date
class - media item's class
author - the author
actor - the actor
director - director
albumArtist - album artist
trackNumber - track number
seriesTitle - series title
seriesID - series ID
episodeNumber - episode number
episodeCount - episode count
channelNr - channel number
channelName - channel name
longDescription - long description
rating - upnp:rating
resolution - resolution
duration - duration
id - @id
refID - @refID
protocolInfo - protocol info
userRating - pv:rating

type - the type
The predefined "type" values are:
musicItem, musicAlbum, musicArtist, musicGenre,
photoItem, photoAlbum,
videoItem,
playlist,
folder,
container,
item

Examples

Find all music tracks that contain FindThis in the title.

type=musicItem&title=FindThis

Find all music tracks in the FindThis album.

type=musicItem&album=FindThis

Find all music tracks with FindThis as the artist, and FindThat as the album.

type=musicItem&artist=FindThis&album=FindThat

Find all music albums with FindThis as the genre.

type=musicAlbum&genre=FindThis

URL encoding of special characters searching for music item.

Actual title: a"&=b

URL encoded string: title=a%22%26%3db&type=musicItem

UPnP Search Syntax

The UPnP Search Syntax grammar is as follows:

	searchCrit ::= searchExp | asterisk
	searchExp ::= relExp | searchExp wChar+ logOp wChar+ searchExp | '(' wChar* searchExp wChar* ')'
	logOp ::= 'and' | 'or'
	relExp ::= property wChar+ binOp wChar+ quotedVal | property wChar+ existsOp wChar+ boolVal
	binOp ::= relOp | stringOp
	relOp ::= '=' | '!=' | '<' | '<=' | '>' | '>='
	stringOp ::= 'contains' | 'doesNotContain' | 'derivedfrom'
	existsOp ::= 'exists'
	boolVal ::= 'true' | 'false'
	quotedVal ::= dQuote escapedQuote dQuote
	wChar ::= space | hTab

Examples

Find all music tracks that contain FindThis in the title.

upnp:class derivedfrom "object.item.audioItem.musicTrack" and (dc:title contains "FindThis")

Find all music tracks in the FindThis album.

upnp:class derivedfrom "object.item.audioItem.musicTrack" and (upnp:album contains "FindThis")

Find all music tracks with FindThis as the artist, and FindThat as the album.

upnp:class derivedfrom "object.item.audioItem.musicTrack" and (upnp:artist contains "FindThis")

Find all music albums with FindThis as the genre.

upnp:class derivedfrom "object.item.audioItem.musicTrack" and (upnp:genre contains "FindThis")

Exact Searches

Find a music track with "FindThis" as the title.

upnp:class derivedfrom "object.item.audioItem.musicTrack" and (dc:title = "FindThis")

Searchable Fields

Items can be searched for by specifying some combination of the following UPnP fields.

res@resolution
res@duration
dc:title
dc:creator
upnp:actor
upnp:artist
upnp:genre
upnp:album
dc:date
upnp:class
@id
@refID
@protocolInfo
upnp:author
dc:description
pv:avKeywords
pv:rating
upnp:seriesTitle
upnp:episodeNumber
upnp:director
upnp:rating
upnp:channelNr
upnp:channelName
upnp:longDescription
pv:capturedate
pv:custom

derivedfrom

derivedfrom can also be one of the following:

object.item
object.item.audioItem.musicTrack
object.item.audioItem.audioBroadcast
object.item.audioItem.online.musicTrack
object.item.imageItem.photo
object.item.imageItem.online.photo
object.item.videoItem.movie
object.item.videoItem.classified.movie
object.item.videoItem.videoBroadcast
object.item.videoItem.online.movie
object.container
object.container.playlistContainer
object.container.musicContainer
object.container.pictureContainer
object.container.videoContainer
object.container.storageFolder
object.container.album.musicAlbum
object.container.album.photoAlbum
object.container.person.musicArtist
object.container.genre.musicGenre

DTCP Support

If the REST API is used with an DTCP-IP enabled Twonky Server, then support for moving or copying DTCP protected content to other DTCP enabled media servers ("DTCP push move") is available.
To help determine if a Twonky Server is DTCP enabled and is supporting this feature, the UPnP device description XML of the server contains the following tags:
<pv:extension xmlns:pv="http://www.pv.com/pvns/">dtcp-push</pv:extension>

To determine if an intended target media server supports this feature, the UPnP device description XML of this server must expose the following tags:
<dlna:X_DLNACAP xmlns:dlna="urn:schemas-dlna-org:device-1-0">av-upload,image-upload,audio-upload,dtcp-copy,dtcp-move</dlna:X_DLNACAP>

These tags and data can be accessed through the web API of the Client SDK through the metadata of a selected media server.

Please see "dtcp_content_upload" and "dtcp_get_capabilities" in the Client SDK RPC for further details on the "DTCP push move" feature.

Document References

Twonky Client SDK Introduction
Twonky Server, Technical Specification and APIs
UPnP Device Architecture 1.1, www.upnp.org
UPnP Media Server:1 and Media Renderer:1, www.upnp.org
DLNA Design Guidelines August 2009, www.dlna.org
UPnP Developer Tools, http://opentools.homeip.net/dev-tools-for-upnp

Glossary

DMS, media server, DLNA MS, UPnP Media Server Device
A UPnP and or DLNA specified media server that implements the UPnP Media Server device specification.
See www.upnp.org and www.dlna.org/industry for further details

DMP, networked media player Device, UPnP Media Player Device
A networked media player device that implements the UPnP Media Player Device specification. A DMP will need a user interface to enable a user to control it to find and select content from a DMS in his network (see also DMR).
See www.upnp.org and www.dlna.org/industry for further details

DMR networked media renderer Device, UPnP AV CP, DLNA MSCP & MRCP
A networked Media Renderer Device that implements a networked media player and offering to be remotely controlled from a DMC. A DMR can be co-located with a DMP or exist „head-less" for remote control only („network media adapter").
See www.upnp.org and www.dlna.org/industry for further details

DMC, UPnP AV CP, DLNA MSCP & MRCP
A networked remote control application used for discovering and controlling media renderers and media servers in a network.
See www.upnp.org and www.dlna.org/industry for further details

DTCP push move
The Web APIs allow to move DTCP-IP protected content to other DTCP-IP enabled media servers.

NMC, Networked Media Controller

Originally specified the high-level API of the Twonky Client SDK. This is going to be cleared, but to keep backwards compatibility with existing applications the abbreviation is kept in the URLs.

Child pages

Twonky Server REST API Specification

Introduction

Use Cases

Concepts

Control point design considerations

REST API

Access Restrictions

RSS

Overview

Accessing the root level

Limiting Response Size

Server List

Server Content

Parent List

Sorting

Renderer List

Renderer Queue

Specifying Start, Count and Format

JSON Formatted Data

JSON Escaping

JSON Root Level

JSON Renderer Queue

Error Response

Twonky server URL options

Requesting Metadata with Specific Adaptation

RPC

Call Syntax

Response Template

Response Messages and Codes

JSON Format

Available RPCs

Controlling HTTP Response Codes

Examples

Retrieving A Renderer Bookmark

Retrieving An Item Bookmark

Checking If A Renderer Can Play An Item (can_play)

Adding A Bookmark To A Renderer Queue (add_bookmark)

Adding An Item Using A URL To A Renderer Queue (add_metadata)

A Full DIDL-Lite XML response from a BrowseMetadata SOAP call

Part of a Full DIDL-Lite XML response

An RSS <meta> XML element (Music)

An RSS <meta> XML element (Photo)

An RSS <meta> XML element (Video)

Adding An Unsupported Item To A Renderer Queue

A second song is added to the end of the queue of the SoundBridge

The second song shall be made the first item in the queue

Play the songs in the queue.

Get the play state.

Get all server and renderer events.

Server and renderer events

Error return codes

Logging source and level

Logging Sources

Logging Levels

Search Syntax

General Search Syntax

Simplified Search Syntax

Examples

UPnP Search Syntax

Examples

Exact Searches

Searchable Fields

derivedfrom

DTCP Support