MediaServer2 D-Bus specification¶
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.
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 should be:
org.gnome.UPnP.MediaServer2.ApplicationName
, for example org.gnome.UPnP.MediaServer2.PulseAudio
.
Rygel shold look for all services on the bus starting with org.gnome.UPnP.MediaServer2.
,
both active ant activatable. It should then do its calls on an entry point object on the
service with the path of /org/gnome/UPnP/MediaServer2/ApplicationName
,
for example /org/gnome/UPnP/MediaServer2/PulseAudio
.
The two ApplicationName suffixes on the service name and the path should be identical.
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 expoised (in UPnP terms: “containers”). MediaItem is for streams/files that are exposed (in UPnP terms “items”).
MediaItem as well as MediaContainer objects need to implement MediaObject.
The entry point object needs to implement the MediaContainer interface (and hence MediaObject).
org.gnome.UPnP.MediaContainer2¶
Methods¶
ListChildren (u Offset, u Max, as Filter) -> (aa{sv} Children)¶
ListChildren will get you a list of property name and value dictionaries, one for each object listed.
Offset
is the zero-based index of the first item in the search result that the caller is
interested in and Max
is the maximum number of objectes to return out of the search result
(0 for no limit). Together these two properties define a window or slice in the result the caller is
interested in, to allow for incremental browsing.
Filter
is an array of property names that the caller is interested in. To fetch all available
properties in the result, clients must pass an array with the single element "*"
.
For the properties, refer to :ref:TBD.
ListChildrenEx (u Offset, u Max, as Filter, s SortBy) -> (aa{sv} Children)¶
ListChildrenEx will get you a list of property name and value dictionaries for all media objects directly under this container.
Note
This method is optional.
Offset
is the zero-based index of the first item in the search result that the caller is
interested in and Max
is the maximum number of objectes to return out of the search result
(0 for no limit). Together these two properties define a window or slice in the result the caller is
interested in, to allow for incremental browsing.
Filter
is an array of property names that the caller is interested in. To fetch all available
properties in the result, clients must pass an array with the single element "*"
.
SortBy
is the name of a property that shall be used to use as a sort key for the returned list.
Note
This function is currently not used by Rygel.
For the properties, refer to :ref:TBD.
ListContainers (u Offset, u Max, as Filter) -> (aa{sv} Children)¶
ListConainers will get you a list of property name and value dictionaries, for all containers under this container.
Offset
is the zero-based index of the first item in the search result that the caller is
interested in and Max
is the maximum number of objectes to return out of the search result
(0 for no limit). Together these two properties define a window or slice in the result the caller is
interested in, to allow for incremental browsing.
Filter
is an array of property names that the caller is interested in. To fetch all available
properties in the result, clients must pass an array with the single element "*"
.
For the properties, refer to :ref:TBD.
ListContainersEx (u Offset, u Max, as Filter, s SortBy) -> (aa{sv} Children)¶
ListConainersEx will get you a list of property name and value dictionaries, for all containers under this container.
Note
This method is optional.
Offset
is the zero-based index of the first item in the search result that the caller is
interested in and Max
is the maximum number of objectes to return out of the search result
(0 for no limit). Together these two properties define a window or slice in the result the caller is
interested in, to allow for incremental browsing.
Filter
is an array of property names that the caller is interested in. To fetch all available
properties in the result, clients must pass an array with the single element "*"
.
SortBy
is the name of a property that shall be used to use as a sort key for the returned list.
It needs to be prefixed with “+” to denote ascending order and “-” for descending order.
Note
This function is currently not used by Rygel.
For the properties, refer to :ref:TBD.
ListItems (u Offset, u Max, as Filter) -> (aa{sv} Children)¶
ListItems will get you a list of property name and value dictionaries, for all items under this container.
Offset
is the zero-based index of the first item in the search result that the caller is
interested in and Max
is the maximum number of objectes to return out of the search result
(0 for no limit). Together these two properties define a window or slice in the result the caller is
interested in, to allow for incremental browsing.
Filter
is an array of property names that the caller is interested in. To fetch all available
properties in the result, clients must pass an array with the single element "*"
.
For the properties, refer to :ref:TBD.
ListItemsEx (u Offset, u Max, as Filter, s SortBy) -> (aa{sv} Children)¶
ListItems will get you a list of property name and value dictionaries, for all items under this container.
Note
This method is optional.
Offset
is the zero-based index of the first item in the search result that the caller is
interested in and Max
is the maximum number of objectes to return out of the search result
(0 for no limit). Together these two properties define a window or slice in the result the caller is
interested in, to allow for incremental browsing.
Filter
is an array of property names that the caller is interested in. To fetch all available
properties in the result, clients must pass an array with the single element "*"
.
SortBy
is the name of a property that shall be used to use as a sort key for the returned list.
It needs to be prefixed with “+” to denote ascending order and “-” for descending order.
Note
This function is currently not used by Rygel.
For the properties, refer to :ref:TBD.
SearchObjects (s Query, u Offset, u Max, as Filter) -> (aa{sv} Result)¶
SearchObjects gets you properties of all media objects anywhere under this container that satisfy the search criteria.
Note
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.
Query
is a search criteria string which is described by the following BNF syntax:
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 *)
The operator precedence, highest to lowest, is:
dQuote
()
binOp, existsOp
and
or
The special value asterisk “*” means to return all media objects.
Examples¶
DisplayName contains "Hello"
Artist = "Michael Jackson" and "Album" = "Thriller"
Bitrate > 256 and (MIMEType = "audio/mpeg" org MIMEType = "audio/ogg")
Offset
is the zero-based index of the first item in the search result that the caller is
interested in and Max
is the maximum number of objectes to return out of the search result
(0 for no limit). Together these two properties define a window or slice in the result the caller is
interested in, to allow for incremental browsing.
Filter
is an array of property names that the caller is interested in. To fetch all available
properties in the result, clients must pass an array with the single element "*"
.
SearchObjectsEx (s Query, u Offset, u Max, as Filter, s SortBy) -> (aa{sv} Result, u TotalMatch)¶
This function is similar to SearchObjectsEx, except for the additional return value TotalMatch
and the additional SortBy
parameter.
SortBy
is the name of a property that shall be used to use as a sort key for the returned list.
It needs to be prefixed with “+” to denote ascending order and “-” for descending order.
TotalMatch
returns the number of all items that match the Query
parameter, which might differ
from the number of dictionaries in the result array if the application used Max
and Offset
for slicing the result.
Note
This function is currently not used by Rygel.
Properties¶
Name |
Type |
m/o [1] |
Description |
---|---|---|---|
ChildCount |
u |
m |
The total number of child media objects. An unknown number of children is indicated by using UINT_MAX. |
Searchable |
b |
m |
Whether the container suppors the Search(). method call. |
ItemCount |
u |
o |
Number of child items. |
ContainerCount |
u |
o |
Number of child containers. |
Icon |
o |
o |
Root container only. Object path of a MediaContainer2 object matching the MediaItem2.Thumbnail property, to be used in user interfaces as a device icon. |
Signals¶
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.
org.gnome.UPnP.MediaItem2¶
Methods¶
MediaItem2 does not have any methods.
Properties¶
Generic properties¶
Name |
Type |
m/o [1] |
Description |
---|---|---|---|
URLs |
as |
m |
List the URLs available. There could be multiple URLs for this item for different transport protocols. It is possible to use simple address substitution in URLs, for details see below |
MIMEType |
s |
m |
The mime-type of the stream. |
Size |
x |
o |
Size of the item in bytes. |
Artitst |
s |
o |
The artist of the item. |
Album |
s |
o |
The album of this item. |
Date |
s |
o |
A date for the item. Must comply to ISO#8601 and RFC#3339 |
DLNAProfile |
s |
o |
The DLNA profile of the item. If you can provide this, Rygel can avoid guessing it. |
URL address substitution¶
When specifiying an URL, it is possible to use the special pattern @ADDRESS
. If this pattern
is following directly after the ://
, it will be replaced with the IP address of the
network interface used to access Rygel. That way a resource can be provided on multiple IP
addresses (think IPv4 and IPv6) without repeating items.
For example, by specifying an URL as http://@ADDRESS@/item/song.mp3
, and Rygel is connected
by the client on the IPv4 address 192.168.2.34, Rygel will present the URI
http://192.168.2.34/item/song.mp3
to the client. If @ADDRESS@
is anywhere else in the
URL, it will be passed as-is.
Applicable for video and audio/music¶
Name |
Type |
m/o [1] |
Description |
---|---|---|---|
Duration |
i |
o |
Duration of the item, in seconds. |
Bitrate |
i |
o |
Bitrate of the audio part of the item, in bits (e.g. 1280000 for an 128kb/s MP3). |
SampleRate |
i |
o |
Sample rate of the audio part of the item, in Hz (e.g. 48000 for a 48kHz WAV). |
BitsPerSample |
i |
o |
Bits per sample for the audio part of the item (e.g. 16 for a 16bit WAV). |
Applicable for video and images¶
Name |
Type |
m/o [1] |
Description |
---|---|---|---|
Width |
i |
o |
Width, in pixels. |
Height |
i |
o |
Height, in pixels. |
ColorDepth |
i |
o |
The colordepth, in bits. |
Thumbnail |
o |
o |
A smaller representation of the item. Special constraints apply, see below. |
Thumbnails¶
The object returned by the Thumbnail
property has special requirements, if provided:
It must implement the
MediaItem2
InterfaceWidth
,Height
andDepth
become mandatory properties.org.gnome.MediaObject2.Type
must beimage
Footnotes