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.

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.

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

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.

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.

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

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

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

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

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.

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.

Moves the item in the queue from the position "index" to the position "toindex".

pause

renderer=[BOOKMARK] resume=[0 | 1]

Pause and restart playing. 0=pause 1=resume playing

play

renderer=<BOOKMARK>

Optional parameters:

mode=<mode>

playspeed=<playspeed>

Play the items in the renderer queue.

Each renderer has exactly one queue and that queue only controls that renderer (1-to-1). Starting playback on a renderer triggers the queue control as specified by the parameters. Starting the playback does not influence the playback on any other renderer. So multiple renderers can be queue controlled concurrently.

The parameter mode consists of play modes and flags. Flags can be combined with one play mode.

Play modes:

0: normal playback

1: shuffle (re-order) queue randomly before playback

2: random playback (order remains)

Flags:

0x100 (256): consume items after playback

0x200 (512): repeat queue

0x400 (1024): repeat single item

0x800 (2048): keep play mode setup as previously set via set_playmode (any other setting is ignored if this is set)

If the parameter is not provided, then 0 is used. The mode needs to be specified as decimal value and contain one play mode and several flags added together.

The playspeed parameter can be used to set the playspeed. Before using this the renderer should be queried about the currently available playspeeds using RPC get_current_playspeeds. The returned values of that RPC can be used as input.

If not provided, then playspeed "1" is used. See also RPC set_playspeed.

Starts normal playback of an item in the queue from a specific position.

Each renderer has exactly one queue and that queue only controls that renderer (1-to-1). Starting playback on a renderer triggers the queue control as specified by the parameters. Starting the playback does not influence the playback on any other renderer. So multiple renderers can be queue controlled concurrently.

Parameters:

renderer: Bookmark of the target renderer to start playback on

bookmark: Bookmark of the queue item to play. The item must be already in the queue. If multiple items with the same bookmark are in the queue, then the first matching one is taken. If not specified, then the first item in the queue is used.

startposms: Start position in ms.

startposbyte: Byte offset to start from.

The RPC tries several approaches to start playback from the specified time/byte position.

If none is supplied, then streaming starts from the beginning. If one of the positions is provided, then this is used. If both are provided, then time seek is used if supported, byte seek otherwise.

A zero or empty position is treated as if the parameter is not provided.

If the renderer supports only byte seek and byte position is not available, then a byte position is calculated from the time position. Similarly if it supports only time seek and time position is not available then time position is calculated from byte position.

Since version 8.1 Twonky Server supports the concept of audiobooks. If such an audiobook is played to a renderer, then ca. every 30s the current playback position is stored on the source server to enable a later resume.

This RPC can be used to reset the audiobook playback position as if it was not played before. There is no distinction of users, ie. invoking the RPC resets the position for all users since as of now the position is not user specific. For servers not in the same process a network connection is required.

Note: Resetting the audiobook position does not lead to a server update event. But the RPC updates all caches. So re-retrieving the metadata of the audiobook container will no longer contain the play position.

The RPC removes from the audiobook container these properties:

pv:playbackBookmark: Bookmark of audiobook track last played

pv:playbackObjectId: Object ID of audiobook track last played

pv:playbackTimeOffset: Last play position in ms for the refered audiotbook track

pv:playbackByteOffset: Last play position in bytes for the refered audiobook track

Invocation with renderer bookmark:

Resets the position of the audiobook currently in the renderer queue.

This requires that the first item of the queue belongs to the audiobook to reset.

This invocation can be used, if the target renderer that played the audiobook is still known and the queue has not been cleared.

If both parameters are provided, then the renderer parameter is ignored.

See: play_from_position

Since 8.1

search

server=[BOOKMARK] search=[hex-encoded query]

Optional parameters:

start=[value]

count=[value]

wkb=[well-known bookmark]

sort=[sort criteria]

fmt=json

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.

To search in a well-known bookmark, provide the server bookmark and the wkb parameter

For further description see chapter Search Syntax.

seek_bytes

renderer=[BOOKMARK] seek=[value]

The seek position is relative to the beginning of the current stream in bytes.

Example: seek=50000 to seek to byte 50000

seek_percent

renderer=[BOOKMARK] seek=[value]

The seek position is relative to the beginning of the current stream in percent.

Example: seek=50 to seek to the middle of the stream

seek_time

renderer=[BOOKMARK] seek=[value]

The seek position is relative to the beginning of the current stream in milliseconds.

Example: seek=50000 to seek to 50s

set_mute

renderer=[BOOKMARK] mute=[0 | 1]

Set mute on or off. 0=off 1 =on

set_playmode

renderer=<BOOKMARK>

Optional parameters:

mode=<mode>

Change the play mode on the fly.

The RPC can be used to either pre-configure the play mode or change it on the fly during playback.To keep the play mode when invoking play RPC, provide value 2048 (keep setup) as play mode to the invocation.

If the mode parameter is missing, then mode 0 is used.

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

The RPC is available since version 7.3.1.

set_playspeed

renderer=<BOOKMARK>

Optional parameter:

playspeed=<playspeed>

Changes the playspeed of the current playback.

Before using this the renderer should be queried about the currently available playspeeds using RPC get_current_playspeeds. The returned values of that RPC can be used as input. If the parameter is not provided, then playspeed "1" is used.

See also get_playspeed and play.

Since 7.2.6.

set_brightness

renderer=[BOOKMARK] brightness=[0..100]

Set brightness (since 7.0.10)

get_brightness

renderer=[BOOKMARK]

Get brightness (since 7.0.10)

set_contrast

renderer=[BOOKMARK]

contrast=[0..100]

Set contrast (since 7.0.10)

get_contrast

renderer=[BOOKMARK]

Get contrast (since 7.0.10)

set_loudness

renderer=[BOOKMARK]

loudness=[0|1]

Set loudness (since 7.0.10)

get_loudness

renderer=[BOOKMARK]

Get loudness (since 7.0.10)

set_playindex

renderer=[BOOKMARK] index=[value]

Skips to the queue item at the specified index (index 0 is the first item in the queue).

Any current playback is interrupted and the item at the given index is continued. If not playing yet, then playback is started using the mode previously set via set_playmode or normal play mode if none was explicitly set.

Note: If the requested item is not supported, then playback stops.

See also: play, skip_next, skip_previous

skip_next

renderer=[BOOKMARK]

Optional parameters:

index=[value]

fmt=json

Skips to the next item in the queue.

The current playback is interrupted and the next supported item in the queue is played on the renderer.

In opposite to set_playindex allows this RPC a smoother transition to the next track. For example in random playback the invocation of this RPC will pick a random unplayed track and not the specified track.Additionally this RPC uses the SetNextAVTransportURI/Next feature if supported by the according renderer. This usually leads to a faster transition to the next track and avoids the renderer going shortly back to the menu.

The index parameter is only used if the queue is not active, ie. it is not yet driven by this control point:

If the queue is inactive and the index is given, then the RPC behaves as if set_playindex had been invoked.

If the queue is active, then the index parameter is ignored.

If the queue is inactive and the index parameter is not provided, then error 31 / "Queue is not active" will be returned.

If the requested item is not supported, then playback stops.

Index 0 is the first item in the queue.

Behavior if queue is active:

If the queue is active and skip fails then queue is stopped.

If skip is done in paused state then state will remain paused

Skips to the next supported queue item, not necessarily to the next item in the queue.

If there are no further supported queue items in the queue, then this skips only to the beginning, if repeat mode was enabled.

Note: The index=5 paramater is given by the caller in case the queue is not active.

See: play, set_playmode, skip_previous, set_playindex

Since 8.1.1

skip_previous

renderer=[BOOKMARK]

Optional parameters:

index=[value]

fmt=json

Skips to the previous item in the queue.

The current playback is interrupted and the previous supported item in the queue is played on the renderer.

The index parameter is only used if the queue is not active, ie. it is not yet driven by this control point:

If the queue is inactive and the index is given, then the RPC behaves as if set_playindex had been invoked.

If the queue is active, then the index parameter is ignored.

If the queue is inactive and the index parameter is not provided, then error 31 / "Queue is not active" will be returned.

If the requested item is not supported, then playback stops.

Index 0 is the first item in the queue.

Behavior if queue is active:

If the queue is active and skip fails then queue is stopped.

If skip is done in paused state then state will remain paused.

Skips to the next supported queue item before the current. If there are no further supported queue items in the queue, then this skips only to the end, if repeat mode was enabled.

In shuffle mode is the queue reshuffled upon the next repeat cycle.

For random playback there is a limited playback history of ten items. If there are items pending in this list, then the skip previous will skip to the previous object in the history. Otherwise it skips to the beginning of the current track. If the history is empty and the current track was deleted, then a random object is taken. The current object is tagged as not played and may be played again in the current round.

13 (not implemented): Remote access is not available on this server, most likely because it is an older version

Since 7.1.2

Discontinued in 7.3

set_slideshow_delay

delay=[seconds]

Sets the global slideshow delay in seconds.The setting affects all renderers.The setting affects any current slideshows.

set_volume_db

renderer=[BOOKMARK] volume=[value]

Set volume in dB (Decibel).

set_volume_percent

renderer=[BOOKMARK] volume=[value]

Set volume. The range of the value is between 0 and 100.

stop

renderer=[BOOKMARK]

Stop playing.

upload

server=[BOOKMARK] file=[value] operation=[start | stop | getstatus]

Uploads a file to the given filename. The name is used as title for the upload and the extension is being used to derive the according content-type.

Can start and stop an upload using the specific operation options. Using the getstatus operation will show the ostensible number of bytes received vs. the total number to be received.

Note: Currently the upload size is limited to 2 MB.

create_item_bookmark

server=[BOOKMARK] objectid=[value]

Creates item bookmark from any server bookmark and object ID.

can_group

renderer=[BOOKMARK]

slave=[BOOKMARK]

Checks if renderer can be added as a slave renderer

add_slave

renderer=[BOOKMARK]

slave=[BOOKMARK]

Add slave renderer

remove_slave

renderer=[BOOKMARK]

slave=[BOOKMARK]

Remove slaver renderer

get_slaves

renderer=[BOOKMARK]

Get list of slave renderers

is_slave

renderer=[BOOKMARK]

Check if renderer in slave mode

is_master

renderer=[BOOKMARK]

Check if renderer is master (has slave renderers)

get_master

renderer=[BOOKMARK]

Get master renderer

set_group_volume

renderer=[BOOKMARK]

volume=[N]

Set volume (in percent) on group of renderers

get_group_volume

renderer=[BOOKMARK]

Get volume (in percent) on group of renderers

set_group_mute

renderer=[BOOKMARK]

mute=[0/1]

Set mute on group of renderers

get_group_mute

renderer=[BOOKMARK]

Get mute on group of renderers

disconnect

renderer=[BOOKMARK]

Disconnect renderer from master

ioctl_nmc

<nmc ioctl>[%20<param>]

Executes a common IOCTL. Param consists of IOCTL to be executed and IOCTL's param if any, separated by %20.

The ioctl name is the value of the ioctl define and not the define itself. Names are case-sensitive. See the NMC_IOCTL defines in tm_nmc_common.h of the Doxygen description for available common ioctls.

In case of an error or if the ioctl does not return a string result the according JSON result is returned as listed in section Response Template above. In case of success and if a non-empty response string is returned by the ioctl, then this string is directly returned.

Example:

http://127.0.0.1:9085/nmc/rpc/ioctl_nmc?SetLogSource%20169

Since 7.0.6

As of 8.2.1 the following IOCTLs are forbidden via RPC:

SetNMCAppName

SetLogFilename

SetNMCDataDirectory

StopNMC

StartNMC

As of 8.2.1 the IOCTLs SetIniProperty and GetIniProperty are rerouted onto the Twonky Server RPCs /rpc/set_option and /rpc/get_option when the NMC RPCs are invoked on Twonky Server or the Twonky SDK with enabled Twonky Server. In this case the responses will have the server format and not the NMC format. Hence, it is recommended to use the server RPCs to set and get INI properties instead if available. See the Twonky Server API documentation for more information about server RPCs.

ioctl_dms

server=<BOOKMARK>

<server ioctl>[%20<param>]

Executes Server IOCTL. First param is server bookmark. Second param is IOCTL to be executed with it's param if any, separated by %20.

The ioctl name is the value of the ioctl define and not the define itself. Names are case-sensitive. See the DMSCP_IOCTL defines in tm_dms_cp.h of the Doxygen description for available server ioctls.

In case of an error or if the ioctl does not return a string result the according JSON result is returned as listed in section Response Template above. In case of success and if a non-empty response string is returned by the ioctl, then this string is directly returned.

Executes Renderer IOCTL. First param is renderer bookmark. Second param is IOCTL to be executed with it's param if any, separated by %20.

The ioctl name is the value of the ioctl define and not the define itself. Names are case-sensitive. See the DMRCP_IOCTL defines in tm_dmr_cp.h of the Doxygen description for available renderer ioctls.

In case of an error or if the ioctl does not return a string result the according JSON result is returned as listed in section Response Template above. In case of success and if a non-empty response string is returned by the ioctl, then this string is directly returned.

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 callerror on creating a contexterror on deleting the contextbookmark not foundexecution of the action failedunknown 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

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")

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.

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.

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