This is the D-Bus interface that can be used by applications that want to have out-of-process media streams exported to other apps. Although originally designed for applications to expose their media to the UPnP world through Rygel, this spec is now planned to be used by non-UPnP applications such as totem or rhythmbox as well.

Theory of operations

Each provider application needs to maintain a hierarchy of media in which each object in the hierarchy is either an item or a container. An item is a playable leaf object and a container is a collection of other containers and/or items. For example, if a provider exposes media in a particular directory on some filesystem, each directory will be exposed as a container and each media file will be exposed as an item.

Entry Point

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

org.gnome.UPnP.MediaServer2.<AppName> 

Example: org.gnome.UPnP.MediaServer2.PulseAudio

Rygel should look for all services on the bus starting with 'org.gnome.UPnP.MediaServer2.', 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/MediaServer2/<AppName>

Example: /org/gnome/UPnP/MediaServer2/PulseAudio

The <AppName> suffix of this entry point path should be identical to 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.MediaObject2
org.gnome.UPnP.MediaContainer2
org.gnome.UPnP.MediaItem2

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

The MediaContainer interface has one signal:

org.gnome.UPnP.MediaContainer2.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.MediaContainer2 objects should implement the standard property interface and simply expose a couple of properties:

u org.gnome.UPnP.MediaContainer2.ChildCount
u org.gnome.UPnP.MediaContainer2.ItemCount
u org.gnome.UPnP.MediaContainer2.ContainerCount
b org.gnome.UPnP.MediaContainer2.Searchable

The 'ChildCount' is the total number of child media objects. An unknown number of children is indicated by using UINT_MAX. ItemCount' and 'ContainerCount' are optional properties specifying the number of child items and containers, respectively. The 'Searchable' flag is set if the container allows searching in it.

The root container could also provide the following optional property:

o org.gnome.UPnP.MediaContainer2.Icon

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

This interface has the following methods:

aa{sv} org.gnome.UPnP.MediaContainer2.ListChildren (IN u offset, IN u max, IN as filter)
aa{sv} org.gnome.UPnP.MediaContainer2.ListContainers (IN u offset, IN u max, IN as filter)
aa{sv} org.gnome.UPnP.MediaContainer2.ListItems (IN u offset, IN u max, IN as filter)

This method gets you properties of all media objects directly under this container. The result is an array of property name+value dictionaries, one for each object listed. 'offset' is the (0-based) index of the first item in the search result that the caller is interested in and 'max_count' is the maximum number of objects to return out of the search result (0 for no limit). Together these two properties define a window/slice in the result the caller is interested in (to allow for incremental searching). 'filter' is an array of property names that caller is interested in. To fetch all (applicable) properties in the result, consumer applications must pass an array containing only one string: "*". The ListContainers and ListItems do exactly the same but only return child containers or items, respectively.

aa{sv} org.gnome.UPnP.MediaContainer2.SearchObjects (IN s query, IN u offset, IN u max, IN as filter)

This method gets you properties of all media objects anywhere under this container (children, grand-children and so on) that satisfy the search criteria. The return value and parameters are the same as ListChildren method above except for 'query' parameter which is the search criteria string with the following EBNF (Extended Backus-Naur Form):

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|lineFeed|vTab|formFeed|return
property     ::= (* property name as defined in Section 2.2.20 *)
escapedQuote ::= (* double-quote escaped string as defined in
                 Section 1.2.2 *)
hTab         ::= (* UTF-8 code 0x09, horizontal tab character *)
lineFeed     ::= (* UTF-8 code 0x0A, line feed character *)
vTab         ::= (* UTF-8 code 0x0B, vertical tab character *)
formFeed     ::= (* UTF-8 code 0x0C, form feed character *)
return       ::= (* UTF-8 code 0x0D, carriage return character *)
space        ::= ' '
                 (* UTF-8 code 0x20, space character *)
dQuote       ::= '"'
                 (* UTF-8 code 0x22, double quote character *)
asterisk     ::= '*'
                 (* UTF-8 code 0x2A, asterisk character *)

Operator precedence, highest to lowest, is:

• dQuote
• ( )
• binOp, existsOp
• and
• or

The special value asterisk (*) means give me all media objects under this container (children, grand-children, grand-children's children and so on).

Examples:

• DisplayName contains "Hello"

• Artist = "Michael Jackson" and Album = "Thriller"

• Bitrate > 256 and (MIMEType = "audio/mpeg" or MIMEType = "audio/ogg")

This method is optional but recommended for containers that expose a large hierarchy. By optional it is meant that you can provide a dummy implementation that always throws DBUS_ERROR_NOT_SUPPORTED but 'Searchable' flags property must be unset in that case.

org.gnome.MediaItem2

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

as org.gnome.UPnP.MediaItem2.URLs
s org.gnome.UPnP.MediaItem2.MIMEType

The 'URLs' property should list the URLs available. There could be more than one URL, for instance, if both http and rtsp are supported. 'MIMEType' should be the mime-type of the stream.

In the 'URLs' array a special string wild card @ADDRESS@ can be used. In a 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.MediaItem2 can also expose these optional properties:

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

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

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

# music
i org.gnome.UPnP.MediaItem2.TrackNumber

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

org.gnome.MediaObject2

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

o org.gnome.UPnP.MediaObject2.Parent
s org.gnome.UPnP.MediaObject2.Type
o org.gnome.UPnP.MediaObject2.Path
s org.gnome.UPnP.MediaObject2.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. 'Type' tells what kind of object we are dealing with and its value must be 'container' in case of container or either of 'video', 'video.movie', 'audio', 'audio.music' 'music', 'image' or 'image.photo' in case of item. The value of 'Path' must be the D-Bus path of the object. The value of 'DisplayName' should be the (possibly localized) display name. Neither of these properties are optional. 'DisplayName' may contain the following magic keywords that are automatically substituted by consumer: