API --- Dleyna-renderer-service is a middleware component. It is designed to be launched by d-Bus activation when needed. It automatically shuts down when the last of its clients quits or releases its connection. Dleyna-renderer-service currently connects to the d-Bus session bus, although this may change in the future. It exposes two different types of objects: 1. A manager object. There is only ever a single instance of this object. It can be used to retrieve a list of the DMRs on the local area network. It is also used to perform certain server independent tasks. 2. Renderer objects. One separate object is exposed for each DMR available on the LAN. These objects expose interfaces that allow clients to retrieve information about the renderers, to manipulate them and to push content to them. The remainder of this document will describe the two d-Bus objects listed above and the interfaces they support. The Manager Object: ------------------- There is only ever a single instance of this object. The manager object exposes a single d-Bus interface, com.intel.dLeynaRenderer.Manager. com.intel.dLeynaRenderer.Manager -------------------------------- Methods: ---------- The interface com.intel.dLeynaRenderer.Manager contains 3 methods. Descriptions of each of these methods along with their d-Bus signatures are given below. GetRenderers() -> ao GetRenderers takes no parameters and returns an array of d-Bus object paths. Each of these paths reference a d-Bus object that represents a single DMR. GetVersion() -> s Returns the version number of dleyna-renderer-service Release() -> void Indicates to dleyna-renderer-service that a client is no longer interested in its services. Internally, dleyna-renderer-service maintains a reference count. This reference count is increased when a new client connects. It is decreased when a client quits. When the reference count reaches 0, dleyna-renderer-service exits. A call to Release also decreases the reference count. Clients should call this method if they intend to keep running but they have no immediate plans to invoke any of dleyna-renderer-service's methods. This allows dleyna-renderer-service to quit, freeing up system resources. Rescan() -> void Forces a rescan for DMRs on the local area network. This is useful to detect DMRs which have shut down without sending BYE messages or to discover new DMRs which for some reason were not detected when either they, or the device on which dLeyna-renderer runs, was started or joined the network. New in version 0.0.2. Signals: --------- The com.intel.dLeynaRenderer.Manager interface also exposes two signals. FoundRenderer(o) Is generated whenever a new DMR is detected on the local area network. The signal contains the path of the newly discovered renderer. LostRenderer(o) Is generated whenever a DMR is shutdown. The signal contains the path of the renderer which has just been shutdown. The Renderer Objects: ------------------ Dleyna-renderer-service exposes a separate d-Bus object for each DMR it detects on the LAN. These objects serve three purposes. 1. They allow the client to retrieve information about the DMR, such as its name, the URL of its icon, its manufacturer, the currently playing content, etc. 2. They allow the client to manipulate the DMR, i.e., to play a given URL, to play, pause and stop, etc. 3. They can be used to implement two box push. Each renderer object exposes three separate interfaces: org.mpris.MediaPlayer2, org.mpris.MediaPlayer2.Player and com.intel.dLeynaRenderer.PushHost. com.intel.dLeynaRenderer.RendererDevice: ---------------------------------------- The com.intel.dLeynaRenderer.RendererDevice interface exposes information about the DMR via a number of d-Bus properties. These properties are described below: |------------------------------------------------------------------------------| | Name | Type | m/o* | Description | |------------------------------------------------------------------------------| | DeviceType | s | m | The UPnP type of the device, e.g., | | | | | urn:schemas-upnp-org:device:MediaServer:1 | |------------------------------------------------------------------------------| | UDN | s | m | The Unique Device Name of the server. | |------------------------------------------------------------------------------| | FriendlyName | s | m | The friendly name of the media server. | -------------------------------------------------------------------------------| | IconURL | s | o | A URL pointing to an icon that | | | | | graphically identifies the server | |------------------------------------------------------------------------------| | Manufacturer | s | m | A string identifying the manufacturer of | | | | | the server | |------------------------------------------------------------------------------| | ManufacturerUrl | s | o | A URL pointing to the manufacturer's web | | | | | site. | |------------------------------------------------------------------------------| | ModelDescription | s | o | A description of the server. | |------------------------------------------------------------------------------| | ModelName | s | m | The model name of the server. | |------------------------------------------------------------------------------| | ModelNumber | s | o | The server's version number | |------------------------------------------------------------------------------| | SerialNumber | s | o | The server's serial number | |------------------------------------------------------------------------------| | PresentationURL | s | o | The presentation URL of the server, i.e., | | | | | a link to it's HTML management interface. | |------------------------------------------------------------------------------| | ProtocolInfo | s | m | A string that identifies all of the file | | | | | formats and network protocol combinations | | | | | that the renderer supports. (1) | |------------------------------------------------------------------------------| | DeviceClasses | as | o | A list of supported device classes, such | | | | | as DMR-1.5, etc. | |------------------------------------------------------------------------------| (* where m/o indicates whether the property is optional or mandatory ) (1) The idea behind the ProtocolInfo property is a little complicated and requires further discussion. The Protocol info field is a comma separated list of protocol info values. Each protocol info value consists of 4 fields separated by colons. Unfortunately, the format is too complex to describe in this document. The reader is referred to the UPnP Connection Manager Service Template document (2) and the DLNA Guidelines (3) where it is described extensively. However, an example protocol info value is presented below, to give the reader an idea of what such a string might look like. "http-get:*:audio/mp4:DLNA.ORG_PN=AMR_WBplus, http-get:*:image/jpeg:DLNA.ORG_PN=JPEG_MED" The ProtocolInfo property identifies the types of URLs the renderer is capable of playing. The example value given above indicates that the renderer is capable of retrieving (via HTTP) and playing/displaying audio MP4 and JPEG files. Now the astute among you might notice that the information provided by the ProtocolInfo property is already available via the standard MPRIS SupportedMimeTypes and SupportedUriSchemes properties. This is true, however ProtocolInfo is still useful as its value is specifically formatted to make it easy to write a certain type of application called a Digital Media Controller (DMC). When you write a DMC you instruct a DMR to play a media file exposed by a Digital Media Server (DMS). DMSs often publish the same piece of media content in a number of formats, exposing a separate URL for each format. The DMC can use the ProtocolInfo of his chosen renderer to determine which of the many formats is most suitable for the renderer and having done this to determine which URL to use. If the DMC uses dleyna-server-service to browse the contents of DMSs, it can achieve this simply by identifying the dleyna-server-service d-Bus object of the file it wishes to play, and then invoking this object's GetCompatibleResource method, passing the renderer's ProtocolInfo string as a parameter. This method will then return the most suitable URL for the renderer. Methods: --------- The com.intel.dLeynaRenderer.RendererDevice interface currently exposes two methods: Cancel() -> void Cancels all requests a client has outstanding on that server. GetIcon(s RequestedMimeType, s Resolution) -> (ay Bytes, s MimeType) Returns the device icon bytes and mime type according to the RequestedMimeType and Resolution parameters. Both RequestedMimeType and Resolution parameters are currently reserved for future use and should be set as an empty string. org.mpris.MediaPlayer2 ---------------------- This interface is part of the MPRIS standard and is documented in the MRPIS D-Bus Interface Specification document [1]. As the interface is well described in this document, this section will focus on the peculiarities of dleyna-renderer-service's implementation of this interface rather than the interface itself. The main points of interest are: - The methods Raise and Quit are implemented but they do nothing. The CanRaise and CanQuit properties necessarily return false. - The property HasTrackList is always set to false. This is because TrackLists are not yet implemented. Hopefully, this will change in the future. - The property CanSetFullscreen is always set to false and Fullscreen is not implemented. - The DesktopEntry is not implemented. org.mpris.MediaPlayer2.Player ----------------------------- Like org.mpris.MediaPlayer2, org.mpris.MediaPlayer2.Player is a standard MPRIS2 interface and is already documented in the MRPIS2 specification. Consequently, this section will only describe the peculiarities of dleyna-renderer-service's implementation of this interface. The main points of interest are noted below: - The LoopStatus property is not implemented. - The Shuffle property is not implemented. - The Seek signal is not implemented yet. - The first parameter to SetPosition is ignored, and any valid d-Bus path can be specified as its value. - PropertiesChanged signals are emitted via the org.freedesktop.DBus.Properties interface of a renderer object instance when org.mpris.MediaPlayer2.Player interface properties value change. - Some new properties have been added, they are described below: |------------------------------------------------------------------------------| | Name | Type |m/o*| Description | |------------------------------------------------------------------------------| | TransportPlaySpeeds | ad | m | Allowed play speed values supported by | | | | | the renderer. It allows clients to set | | | | | the Rate property with a value that will | | | | | be accepted by the DMR. | |------------------------------------------------------------------------------| | CurrentTrack | u | m | The sequence number of the currently | | | | | selected track. | |------------------------------------------------------------------------------| | NumberOfTracks | u | m | The number of tracks in the currently | | | | | selected media. | |------------------------------------------------------------------------------| | Mute | b | o | The mute setting of the master audio | | | | | channel. New in version 0.0.2. | |------------------------------------------------------------------------------| | CanByteSeek | b | m | Whether the client can control the | | | | | playback position using ByteSeek and | | | | | SetBytePosition. | |------------------------------------------------------------------------------| | BytePosition | x | o | The current track position in bytes. | |------------------------------------------------------------------------------| - new methods have been added, they are described below: GotoTrack(u TrackNumber) -> void Performs a seek operation to the specified track number. OpenUriEx(s Uri, s Metadata) -> void Same as the OpenUri method of the org.mpris.MediaPlayer2.Player MPRIS2 standard interface, with an additional parameter Metadata to specify the DIDL-Lite XML description of the item to be opened. New in version 0.0.2. OpenNextUri(s Uri, s Metadata) -> void Same as OpenUriEx method but for enabling an early download of the next object. New in version 0.2.0. SetUri(s Uri, s Metadata) -> void Same as OpenUriEx except that it doesn't automatically play the media. You need to explicitely call the Play method. New in version 0.2.0. ByteSeek(x Offset) -> void SetBytePosition(o TrackID, x Position) -> void Same as Seek and SetPosition but last parameter (Offset and Position) is not expressed in second but in byte, and allows to set the seekmode to respectively “REL_COUNT” and “ABS_COUNT” . New in version 0.2.1 org.mpris.MediaPlayer2.TrackList and org.mpris.MediaPlayer2.Playlists --------------------------------------------------------------------- Are not yet implemented. com.intel.dLeynaRenderer.PushHost --------------------------------- DMRs participate in two different DLNA use cases. 3 Box System and 2 Box Push. In the 3 Box System a DMC instructs a DMR to play a URL hosted by a DMS. In 2 Box Push, an application pushes content it has created or downloaded directly to a renderer. In 2 Box Push the DMS is not involved at all and this presents a problem as DMRs do not really support the concept of Push. Rather than pushing files to a DMR, the client passes it a URL and then instructs the DMR to pull the content from the URL. For this to work, a web server must be running somewhere to host the URL. In the 3 Box System the role of the web server is played by the DMS. Unfortunately, as we have seen, in 2 Box Push there is no DMS. So who is to host the content to be pushed? Conceptually, each application that wishes to push a file to a DMR could start its own web server on which it could temporarily host the file to be pushed. However, this is complicated for application developers and also wasteful of system resources. Potentially, every application that can create of download content can push this content to DMRs. As, these applications can legitimately run simultaneously having them run their own web servers would consume unnecessary system resources. Dleyna-renderer-service solves these problems by providing both a web server and simple APIs that can be used by clients to host files on this server. As only one instance of dleyna-renderer-service runs at any one time (well currently only one can run per user session) we avoid the proliferation of web servers. These push APIs are provided by the com.intel.dLeynaRenderer.PushHost interface which is implemented by all renderer objects. com.intel.dLeynaRenderer.PushHost contains two methods which are described in below. HostFile(s path) -> s Hosts a file on dleyna-renderer-service's web server. The parameter path should be a full path to the local file to be hosted, e.g., /home/user/Podcasts/pod.mp3. The value returned is the URL of the newly hosted file. RemoveFile(s path) -> void Stops hosting the file whose full path is passed as parameter to this function. Dleyna-renderer-service only runs a web server when files are being hosted. Once all clients have stopped hosting files, either by calling RemoveFile or by exiting, dleyna-renderer-service will shut down its web server. Actually, dleyna-renderer-service may run more than one web server if multiple DMRs are accessed over different interfaces. When a client chooses to host a file for a given renderer, dleyna-renderer-service checks to see if a web server is already running on the interface through which this renderer is accessible. If it is not it starts a new web server. It follows that if clients try to host multiple files for multiple renderers running on different interfaces, dleyna-renderer-service may actually run multiple servers. However, it will only run one server per interface, and the server will be shutdown as soon as it no longer has any files to host. References: ----------- 1) MRPIS D-Bus Interface Specification (http://specifications.freedesktop.org/mpris-spec/latest/) 2) ConnectionManager:2 Service Template (http://www.upnp.org/) 3) DLNA Guidelines December 2011, Part 1 Architectures and Protocols (http://www.dlna.org/)