Twonky Server REST API Specification 2017.05.24 Lynx Technology Copyright © 2017 by Lynx Technology. This document and the information contained herein is the confidential information of Lynx Technology and is for the sole use of the intended recipient(s). If you are not the intended recipient, please contact Lynx Technology at the address listed below and destroy all copies of this document. To the extent a nondisclosure agreement or other commercial agreement (Governing Agreement) is signed and in effect between Lynx Technology (or an authorized Lynx Technology licensee) and the intended recipient(s) of this document, the terms of such Governing Agreement will govern. If no Governing agreement is in effect, then this document may not be used, reproduced or distributed without the prior written consent of Lynx Technology, 10620 Treena St, Suite 230, San Diego, CA 92131. Table of Contents 1 Introduction .......................................................................................................................................... 4 1.1 Use Cases.................................................................................................................................................... 4 1.2 Concepts..................................................................................................................................................... 4 1.3 Control point design considerations ......................................................................................................... 5 2 REST API ................................................................................................................................................ 6 2.1 Access Restrictions .................................................................................................................................... 6 2.2 RSS ............................................................................................................................................................. 6 2.2.1 Overview ............................................................................................................................................................... 6 2.2.2 Accessing the root level ......................................................................................................................................... 7 2.2.3 Limiting Response Size .......................................................................................................................................... 8 2.2.4 Server List ............................................................................................................................................................. 9 2.2.4.1 Server Content ............................................................................................................................................. 15 2.2.4.2 Parent List .................................................................................................................................................... 19 2.2.4.3 Sorting ......................................................................................................................................................... 20 2.2.5 Renderer List ........................................................................................................................................................ 21 2.2.6 Renderer Queue ................................................................................................................................................... 24 2.2.7 Specifying Start, Count and Format ..................................................................................................................... 28 2.2.8 JSON Formatted Data .......................................................................................................................................... 29 2.2.8.1 JSON Escaping ............................................................................................................................................. 29 2.2.8.2 JSON Root Level ..........................................................................................................................................30 2.2.8.3 JSON Renderer Queue ................................................................................................................................. 31 2.2.9 Error Response ..................................................................................................................................................... 34 2.2.10 Twonky server URL options ............................................................................................................................. 34 2.2.11 Requesting Metadata with Specific Adaptation ............................................................................................... 35 2.3 RPC ........................................................................................................................................................... 36 2.3.1 Call Syntax ............................................................................................................................................................36 2.3.2 Response Template ..............................................................................................................................................36 2.3.3 Response Messages and Codes ............................................................................................................................ 37 2.3.4 JSON Format ....................................................................................................................................................... 40 2.3.5 Available RPCs ..................................................................................................................................................... 40 2.3.6 Controlling HTTP Response Codes ....................................................................................................................... 61 2.3.7 Examples .............................................................................................................................................................. 61 2.3.7.1 Retrieving A Renderer Bookmark ................................................................................................................ 61 2.3.7.2 Retrieving An Item Bookmark ...................................................................................................................... 62 2.3.7.3 Checking If A Renderer Can Play An Item (can_play) ...................................................................................63 2.3.7.4 Adding A Bookmark To A Renderer Queue (add_bookmark) ......................................................................63 2.3.7.5 Adding An Item Using A URL To A Renderer Queue (add_metadata) ........................................................ 64 2017 Lynx Technology Proprietary and Confidential 2.3.7.6 A Full DIDL-Lite XML response from a BrowseMetadata SOAP call ............................................................ 64 2.3.7.7 Part of a Full DIDL-Lite XML response ..........................................................................................................65 2.3.7.8 An RSS <meta> XML element (Music) ..........................................................................................................65 2.3.7.9 An RSS <meta> XML element (Photo) ........................................................................................................ 66 2.3.7.10 An RSS <meta> XML element (Video) ..........................................................................................................67 2.3.7.11 Adding An Unsupported Item To A Renderer Queue .................................................................................. 68 2.3.7.12 A second song is added to the end of the queue of the SoundBridge ........................................................ 69 2.3.7.13 The second song shall be made the first item in the queue ........................................................................ 69 2.3.7.14 Play the songs in the queue. ........................................................................................................................70 2.3.7.15 Get the play state. ........................................................................................................................................70 2.3.7.16 Get all server and renderer events. .............................................................................................................. 71 2.3.7.17 Server and renderer events ......................................................................................................................... 71 2.3.7.18 Error return codes ........................................................................................................................................ 72 2.3.8 Logging source and level ...................................................................................................................................... 72 2.3.8.1 Logging Sources .......................................................................................................................................... 72 2.3.8.2 Logging Levels ............................................................................................................................................. 73 2.4 Search Syntax............................................................................................................................................73