WARNING: This spec is deprecated in favor of version 2 of this spec.

This is the D-Bus interface that can be used by applications that want to have out-of-process media streams exported to UPnP world by Rygel. The spec is kept generic enough so other applications can also use it and implementing applications don't need to do anything Rygel specific.

Entry Point

Service name on the *SESSION* bus (later maybe on user bus if Lennart's patches go through) should be:

org.gnome.UPnP.MediaServer1.<AppName> 

Example: org.gnome.UPnP.MediaServer1.PulseAudio

Rygel should look for all services on the bus starting with 'org.gnome.UPnP.MediaServer1.', both active and activatable. It should then do its calls on an entry point object on the service with the path of:

/org/gnome/UPnP/MediaServer1/<AppName>

Example: /org/gnome/UPnP/MediaServer1/PulseAudio

The <AppName> suffix of this entry point path should be identical the <AppName> suffix of the service name on the bus.

Interfaces

The objects that are implemented by services of this type can have the following interfaces:

org.gnome.UPnP.MediaObject1
org.gnome.UPnP.MediaContainer1
org.gnome.UPnP.MediaSearch1
org.gnome.UPnP.MediaItem1

MediaContainer is for directories that are exposed (in UPnP speak: "containers"). MediaItem is for streams/files that are exposed (in uPnP speak: "items"). MediaItem as well as MediaContainer objects need to implement MediaObject. The entry point object needs to implement the MediaContainer interface (and hence MediaObject, too).

The entry-point object must implement the MediaContainer interface.

org.gnome.UPnP.MediaContainer1

The MediaContainer interface has one signal:

org.gnome.UPnP.MediaContainer1.Updated()

Which shall be triggered when a new child item is created or removed from the container, or one of the existing child items is modified, or any of the properties of the container itself are modified. While the signal should be emitted when child containers are created or removed, it shall not be emitted when child containers are modified: instead the signal should be emitted on the child in this case.

The org.gnome.UPnP.MediaContainer1 objects should implement the standard property interface and simply expose a couple of properties, no methods. For now only four:

ao org.gnome.UPnP.MediaContainer1.Items
u org.gnome.UPnP.MediaContainer1.ItemCount
ao org.gnome.UPnP.MediaContainer1.Containers
u org.gnome.UPnP.MediaContainer1.ContainerCount

The 'Items'/'Containers' props get you all the child media objects while 'ItemCount'/'ContainerCount' is the number of child media objects.

The root container could also provide the following optional property:

o org.gnome.UPnP.MediaContainer1.Icon

This is used by client UIs to represent this media server. The value must be an object implementing org.gnome.MediaItem1 implementation with the same constraints/symantics as org.gnome.MediaItem1.Thumbnail property explained below except that the resolution must be either "120x120" or "160x160".

org.gnome.UPnP.MediaSearch1

This interface is optional but recommended. If the application decides to implement it, it must be implemented on each object implementing MediaContainer interface. This interface has the following method:

ao org.gnome.UPnP.MediaSearch1.Search (IN o Container, IN s SearchCriteria)

The !Container is the root container of the subtree in which to perform the search. The SearchCriteria is the string describing the search. The syntax and symantics of SearchCriteria is exactly the same as that of SearchCriteria parameter of UPnP ContentDirectory spec. Applications can make use of API provided by GUPnP to parse this string. This method returns array of objects that qualify the SearchCriteria.

org.gnome.MediaItem1

Similarly org.gnome.MediaItem1 objects expose the following properties, (no methods here either):

as org.gnome.UPnP.MediaItem1.URLs
s org.gnome.UPnP.MediaItem1.MIMEType
s org.gnome.UPnP.MediaItem1.Type

The 'URLs' property should list the urls available. Could be more than one if http and rtsp are supported. 'MIMEType' should be the mime-type of the stream. , 'Type' tells what kind of object we are dealing with and it's value must be either of "video', 'audio', 'music' or 'image'. Neither of these properties are optional.

In the 'URLs' array a special string wild card @ADDRESS@ can be used. In an URL, if the string immediately following the protocol specification and the :// is @ADDRESS@ (uppercase) it will be replaced by the server address used for communication with the client when the URL is passed to the client. If the string @ADDRESS@ is used in any other part of the URL passed it will be left unmodified. It is assumed that the application listens on both IP4 and IPv6 and on all interfaces when passing such a wildcarded URL to Rygel. Example:

http://@ADDRESS@/foo/bar.mp3

Is converted to this before the URL is passed to the clients:

http://192.168.47.11/foo/bar.mp3

The org.gnome.MediaItem1 can also expose these optional properties:

i org.gnome.UPnP.MediaItem1.Size            # in units of bytes
s org.gnome.UPnP.MediaItem1.Artist
s org.gnome.UPnP.MediaItem1.Album
s org.gnome.UPnP.MediaItem1.Date            # must be compliant to ISO#8601 and RFC#3339.
s org.gnome.UPnP.MeidaItem1.Genre
s org.gnome.UPnP.MediaItem1.DLNAProfile

# video and audio/music
i org.gnome.UPnP.MediaItem1.Duration        # in units of seconds
i org.gnome.UPnP.MediaItem1.Bitrate
i org.gnome.UPnP.MediaItem1.SampleRate
i org.gnome.UPnP.MediaItem1.BitsPerSample

# video and images
i org.gnome.UPnP.MediaItem1.Width
i org.gnome.UPnP.MediaItem1.Height
i org.gnome.UPnP.MediaItem1.ColorDepth
i org.gnome.UPnP.MediaItem1.PixelWidth
i org.gnome.UPnP.MediaItem1.PixelHeight
o org.gnome.UPnP.MediaItem1.Thumbnail
 
# audio and music
o org.gnome.UPnP.MediaItem1.AlbumArt

The objects returned by the "!Thumbnail" and "AlbumArt" props (if provided) must implement the org.gnome.MediaItem1 interface and the values of 'width', '!Height' and '!Depth' must be provided and '!Type' must be 'image' for these objects. If you provide "!DLNAProfile" property, it will greatly help avoiding guessing of it's value by Rygel (gupnp-av actually).

org.gnome.MediaObject1

The common interface org.gnome.UPnP.MediaObject1 should only expose properties:

o org.gnome.UPnP.MediaObject1.Parent
s org.gnome.UPnP.MediaObject1.DisplayName

The value of 'Parent' should refer to the container this object is in. For the root container this shall refer to itself, the root container. The value of 'DisplayName' should be the (possibly localized) display name. 'DisplayName' may contain the following magic keywords that are automatically substituted by Rygel: