Skip to content

Content Directory Metadata

Ronen Mizrahi edited this page Jan 21, 2015 · 1 revision

TVersity Media Server Metadata Reference

This Article describes the metadata provided by the TVersity Media Server on a per object class basis.

Introduction

This document describes the metadata provided by the TVersity Media Server to UPnP clients. The document is focusing in the optional properties, since all the mandatory ones, as specified in the Content Directory 1.0 (CDS) standard (section 2.4.3) , are supported. To be consistent with the CDS The properties are listed on a per object class basis, however only classes that are used by TVersity are listed.

The metadata provided by the TVersity media server is derived from the following sources:

  • File system.
  • Metadata embedded in the media file (typically called tags). TVersity supports ID3v1, ID3v2, Ogg Vorbis comments in Ogg, FLAC, and MPC/Ape, iTunes AAC tags, MPEG4 tags, ASF tags (WMA, WMV, DVR-MS) and AVI tags.
  • Internet metadata repositories are used to complement the metadata available locally.

Please note that some properties are always provided while others are available only for some items, depending on the ability of the media server to extract the relevant metadata. Media players should take this into account and gracefully handle these situations. As per the UPnP standard, the metadata is provided in UTF8 encoding.

Metadata issues unique to the TVersity Media Server

One unique aspect of the TVersity Media Server is that it recognizes the UPnP client device (via the HTTP User-Agent) and adapts the metadata accordingly. Each supported device has a device profile that specifies how the metadata (and the media) need to be adapted for that device. The term UPnP client device used throughout this document, refers to devices that implement at least the control point UPnP standard and that interact with the media server for the purpose of browsing, searching and playing media.

The on-the-fly adaptation of metadata described above, is particularly important with the res property, thanks to its automatic device detection and transcoding capabilities, the TVersity Media Server provides exactly one res element per item such that the provided value is optimized for the given client.

While providing a single res element is compliant with the standard, the UPnP standard recommends a different approach. According to the standard, media servers capable of transcoding, may provide one res property per media format they support via transcoding, leaving it up to the UPnP control point to choose the most appropriate one. This recommendation was not adopted by the TVersity Media Server since it is simply impractical:

  • In order to support a wide range of devices, the media server needs to provide many different res elements, based on the useful combinations of codecs, mime types, bitrates, resolutions, sampling rates and all the other relevant media characteristics. This ends up being a very large number, larger than what can be considered manageable.
  • Further to that the UPnP standard suggests keeping the XML files exchanged between the various devices as small as possible to promote better response times and to avoid overloading the network and client devices. Providing many res elements contradicts this.
  • Finally, the standard is suggesting to leave the complex tasks to devices that are not resource constrained, yet in this particular case it shifted the complexity from the resource abundant server to the resource constrained control point.

One other unique aspect of the TVersity Media Server is its support for Internet content (this is in addition to content local to the home network). The metadata for Internet content is typically extracted from one of the common web syndication formats, such as RSS, ATOM, OPML, RDF, etc. When the term "RSS feed" is used in this document, it is just a short form for all the other syndication formats mentioned above. In all these cases the UPnP client receives the metadata in DIDL-Lite format as per the UPnP standard and in fact as far as the UPnP client is concerned, Internet media is indistinguishable from local media.

The TVersity Media Server can also provide additional properties not included in the UPnP standard. To remain standard compliant these properties are disabled by default and can be enabled via the device profile when required.

Metadata Properties by Class

object (Base Class)

Property Name Always exists Name Space Remarks
id Yes didl-lite The standard defines container id 0 as the root and the root parent id is defined as -1. In addition to that, the TVersity Media Server supports direct access to children of the root, which often are the top level menu entries (audio, photo, video, etc.). To achieve that, standard container IDs can be assigned to children of the root via the device profile.

To be consistent with similar assignments proposed by Microsoft we recommend the following:

Container id Container Type
1 Audio
2 Video
3 Image
20 Internet


Property Name Always exists Name Space Remarks
parentID Yes didl-lite
title Yes dc
class Yes upnp
restricted Yes didl-lite Always restricted since clients cannot modify the hierarchy
writeStatus Yes upnp Always set to UNKNOWN.
description No dc Typically available for RSS feed items.
longDescription No upnp Typically available for RSS feed items.
icon See remarks upnp Whenever an image can be associated with objects a smaller version of that image is provided via the icon property. The icon is always available for images, RSS feed items that are an image or have an image associated with them in the feed, music tracks that have album art, album containers that have album art and so on.
rating No upnp Rating of the object's resource, may be used for parental control filtering purposes.

The possible values are (Property is typically assigned by end users or for web content can be derived from RSS feeds):

Value Meaning
explicit explicit content (need parental control pin code if UPnP client supports it).
clean content is clean (no need for parental control pin code ).
Unknown the rating is unknown (was never assigned).
Absence of property means unknown.

Additional Object properties

The following properties are provided only for Internet media assuming the media server were able to retrieve those values.

Property Name Always exists Name Space Remarks
creator No upnp
producer No upnp
actor No upnp
director No upnp
language No dc
relation See remarks dc The original web URL of the media. Always exists for web content. More than one value may be provided since more than one web URLs may be associated with the content.
rights No dc

item: object

Property Name Always exists Name Space Remarks
res Yes didl-lite TVersity provides only one resource per item. This resource is either in the original item format or when a device profile exists adapted to the device capabilities.
res@protocolInfo Yes didl-lite The standard says that if this property is not present, then the content has not yet been fully imported and is not yet accessible for playback purposes. This is typically needed when clients create new objects and then upload a resource. Since TVersity does not support these operations, it does not need to list an item in the content directory unless it is accessible for playback purposes. The 4th field values proposed by the DLNA standard are omitted by default, but can be enabled for UPnP clients that require these values. More specifically when enabled the 4th field values will be: *DLNA.ORG_PN=<DLNA profile>: profile depends on the format and encoding characteristics of the given media. *DLNA.ORG_OP=01: only HTTP RANGE headers are supported by TVersity. TimeSeekRange.DLNA.ORG is not supported. *DLNA.ORG_PS=<comma delimited list of playback speed>: only relevant when server side trick mode is enabled for the given device. In the same time when server side trick mode is indeed enabled and supported for the given media, this value will always be provided.
res@size See remarks didl-lite TVersity makes every effort to always provide this property. For local media it is indeed always provided, for Internet content it is provided when it can be extracted from one of: RSS feed, HTTP headers or can be estimated via duration and bitrate. For media transcoded on-the-fly this is always an estimation since the size will only be known when the transcoding is complete. Same value will be reported in HTTP Content-Length header. When transcoding ends the data will be zero-padded to allow for this size to be met. Alternatively the connection can be closed (in such a case the client should make a new HTTP request to determine if the connection was closed due to some error or because the transcoding ended. Subsequent HTTP requests will return correct size since now it is known). The device profile determines which mode of operation is used.
res@duration See remarks didl-lite Will always have a value for both local and Internet audio/video items unless the media file was corrupt or malformed or the Internet media is a live stream. Will never have value for image items.
res@bitrate See remarks didl-lite Will always have a value for both local and Internet audio/video unless the media file was corrupt or malformed or the bitrate was unavailable due to variable bitrate (VBR) encoding. Will never have value for image items.
res@lastPosition No didl-lite Byte position of last playback on the current STB. Omitted when the media was never played. Will never have value for image items.
res@lastPositionMostRecent No didl-lite Byte position of most recent last playback from any STB. Omitted when the media was never played. Will never have value for image items.
playlist See remarks upnp Always exists for items that appear in at least one playlist or RSS feed.

container: object

Property Name Always exists Name Space Remarks
childCount Yes didl-lite
searchable Yes didl-lite Always set to Yes

audioItem: item

Property Name Always exists Name Space Remarks
artist Yes upnp Will hold the artist name for audio items with an artist tag or RSS feed items with artist information. Otherwise will be Unknown Artist.
album Yes upnp Will hold the album name for audio items with an album tag or RSS feed items with album information. Otherwise will be Unknown Album.
genre Yes upnp Will hold the genre for audio items with a genre tag or RSS feed items with genre information. Otherwise will be Unknown Genre.
res@sampleFrequency See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed.
res@bitsPerSample See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed. Typically equal to 16.
res@nrAudioChannels See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed. Typically 1 or 2.
res@audioBitrate No Audio bitrate in bytes/seconds of the encoding of the resource. For audio items it is same as bitrate, for video items it is not.
res@ audioCodec No The audio codec for examples mp3, aac, vorbis, etc. List of possible values is available at: TVersity RSS extensions

musicTrack : audioItem

Property Name Always exists Name Space Remarks
originalTrackNumber No upnp Will only have value for playlist items and music tracks with an album track number tag.
date See remarks dc Will hold the release year for music track with a year tag. Otherwise will be omitted. The year will have 01-01 appended to it in order to form a full date. This is required in order to comply with the UPnP standard specification pertaining to dc:date.
albumArtURI No upnp Will hold URI for album art (aka CD cover art) JPEG image when art was available. Otherwise will be omitted. This image is typically higher resolutions than upnp:icon.

audioBroadcast : audioItem

The audioBroadcast class is used for live Internet radio stations. There are no additional properties for this class beyond what was described above.

videoItem : item

Property Name Always exists Name Space Remarks
album Yes upnp Will hold the album name for video items with an album tag or RSS feed items with album information. Otherwise will be Unknown Album.
genre Yes upnp Will hold the genre for video items with a genre tag or RSS feed items with genre information. Otherwise will be Unknown Genre.
publisher Yes dc Will hold the publisher for video items with a publisher tag or RSS feed items with publisher information. Otherwise will be Unknown publisher.
res@sampleFrequency See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed.
res@bitsPerSample See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed. Typically equal to 16.
res@nrAudioChannels See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed. Typically 1 or 2.
res@resolution See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed.
res@audioBitrate No Audio bitrate in bytes/seconds of the encoding of the resource. For audio items it is same as bitrate, for video items it is not.
res@ audioCodec No The audio codec for examples mp3, aac, vorbis, etc. List of possible values is available at: TVersity RSS extensions
res@videoBitrate No Video bitrate in bytes/seconds of the encoding of the resource.
res@videoCodec No The video codec for examples h264,mpeg2, etc. List of possible values is available at: TVersity RSS extensions
res@videoFPS No Frames per second in fraction (numerator/denominator) format, for example: 30000/1001

videoBroadcast: videoItem

The videoBroadcast class is used for live Internet broadcasts. There are no additional properties for this class beyond what was described above.

photo: imageItem

Property Name Always exists Name Space Remarks
album Yes upnp The name of the folder in which the image resides.
date Yes dc Date in which the photo was taken.
res@resolution See remarks didl-lite Will always have a value for both local and Internet media unless the media file was corrupt or malformed.

musicAlbum : album

Property Name Always exists Name Space Remarks
albumArtURI No upnp Will hold URI for album art (aka CD cover art) JPEG image when art was available. Otherwise will be omitted. This image is typically higher resolutions than upnp:icon.

photoAlbum : album

There are no additional properties for this class beyond what was described above.

genre : container

There are no additional properties for this class beyond what was described above.

musicGenre : genre

There are no additional properties for this class beyond what was described above.

playlistContainer : container

TVersity uses this class for container that holds playlist items (can be music, video and photos). This class is also used for the container of RSS feed items.

Property Name Always exists Name Space Remarks
upnp:author No Will hold the name of the author of the playlist or RSS feeds. For example, when the RSS feed represents a podcast, this is typically the publishing company behind the podcast. When the RSS feed represents a photo stream it is typically the owner of that stream.

musicArtist : person

There are no additional properties for this class beyond what was described above.

storageFolder : container

Property Name Always exists Name Space Remarks
storageUsed Never upnp This is required by the standard, yet omitted by TVersity since it does not provide useful information.
You can’t perform that action at this time.