ISO/IEC IEC 29341-16-10:2011 — UPnP AV ContentDirectory Service

Understanding the ContentDirectory Service

ISO/IEC 29341-16-10:2011 defines the ContentDirectory:2 service, the component responsible for organizing, browsing, and searching media content on UPnP AV Media Servers. The ContentDirectory service (CDS) presents a hierarchical view of available media items — music, video, images, and playlists — organized in a tree structure of containers and items. This service is the primary interface through which control points discover available content and retrieve the metadata and resource information needed to initiate media playback.

The service is identified by urn:schemas-upnp-org:service:ContentDirectory:2 and maintains state variables including SystemUpdateID, ContainerUpdateIDs, SearchCapabilities, SortCapabilities, and FeatureList. The SystemUpdateID is a monotonically increasing integer that increments whenever any change occurs in the content hierarchy. Control points cache this value and compare it with their local copy to determine whether the content directory has changed since their last browse operation. The ContainerUpdateIDs variable provides a more granular change notification by listing specific containers that have been modified along with their individual update IDs.

The ContentDirectory:2 revision introduced significant enhancements over version 1, including: support for fragments within items (allowing references to chapters or time ranges within a media resource), the CreateObject() action for adding new content, the DeleteObject() and UpdateObject() actions for content management, enhanced search capabilities with a broader set of search classes, and the FeatureList state variable for advertising advanced capabilities such as extended query language support.

Content Hierarchy and Object Model

The CDS organizes content using a tree structure of containers and items. Containers are analogous to directories in a filesystem — they can hold other containers and items. Items represent individual media resources and cannot contain other objects. Each object in the tree is uniquely identified by a persistent ObjectID string. The root container has the predefined ID 0. The standard defines a set of upnp:class values that categorize objects: object.container for containers, object.item for items, with specialized subclasses such as object.item.audioItem.musicTrack, object.item.videoItem.movie, and object.item.imageItem.photo.

Each object carries metadata properties drawn from Dublin Core (dc:title, dc:creator, dc:date), UPnP-specific properties (upnp:artist, upnp:genre, upnp:albumArtURI), and resource descriptors (res@protocolInfo, res@bitrate, res@duration, res@size, res@resolution). The res elements are particularly important because they contain the actual URLs from which the media content can be fetched. Each item can have multiple res elements representing the same content in different formats, bitrates, or resolutions, enabling adaptive streaming and format negotiation without requiring multiple items in the content tree.

The Browse() action is the primary mechanism for navigating the content tree. It accepts seven arguments: ObjectID, BrowseFlag (BrowseDirectChildren or BrowseMetadata), Filter, StartingIndex, RequestedCount, SortCriteria, and Filter. The BrowseFlag determines whether the response contains the direct children of the specified container or just the metadata of the container itself. The Filter argument is a comma-separated list of property names that the control point is interested in — the server should return only the requested properties to minimize response size. The StartingIndex and RequestedCount arguments enable pagination of large result sets, which is essential for clients with limited memory buffers and for optimizing network utilization.

Search Capabilities and Metadata Filtering

The Search() action extends browse functionality by allowing control points to query the content tree using a structured search criterion. The search syntax follows the property operator value pattern, with boolean combinators AND and OR. The SearchCapabilities state variable advertises which properties support search operations. Typical searchable properties include dc:title, dc:creator, upnp:artist, upnp:genre, and upnp:class. The comparison operators include contains (substring match), derivedfrom (class hierarchy match), exists, =, !=, <, >, <=, and >=. Search criteria can be nested using parentheses for complex boolean expressions.

Example search criterion: upnp:class derivedfrom "object.item.audioItem" and dc:title contains "symphony". This query returns all audio items whose title contains the word “symphony.” The search is case-insensitive by convention but the standard does not mandate this — implementations should document their case-sensitivity behavior. The SortCriteria argument supports sorting by multiple properties, specified as a comma-separated list with optional direction qualifiers (:asc or :desc). The SortCapabilities state variable lists which properties support sorting.

The Filter argument deserves special attention from implementors. When a control point specifies a Filter list, the server should return ONLY the requested properties. This is a performance optimization that becomes critical for mobile control points on bandwidth-constrained wireless networks. A well-implemented CDS server can reduce response size by 60-80% when the control point only needs the title, class, and resource URL for each item, compared to returning all available metadata. The standard allows special values: * means return all properties, and @ means return only the ID and class.

Engineering Insights for ContentDirectory Implementation

Implementing a high-performance ContentDirectory:2 service requires careful architecture decisions. The object database should support transactional updates to maintain consistency between the SystemUpdateID and individual container update IDs. When content changes — whether through UPnP actions (CreateObject, DestroyObject, UpdateObject) or external modifications (filesystem changes, media import) — the CDS must atomically update the content tree and increment the relevant update counters. Failure to maintain consistency causes control points to receive stale data or miss content change notifications.

The ImportResource and ExportResource actions enable content transfer between devices. These actions work with the ConnectionManager service to establish a data channel for content migration. The CDS tracks the transfer progress through the TransferProgress and TransferStatus variables. Engineering challenge: transfers can be interrupted by network failures or device reboots. Implement checkpointing that saves transfer state at regular intervals, allowing resumption from the last checkpoint rather than restarting from zero. The standard defines transfer states including NotStarted, InProgress, Cancelled, Completed, and Error.

Another critical implementation detail is handling the @childCount property on containers. This property reports the number of direct children (containers + items) within a container. The server must count children efficiently without enumerating all entries — maintain a persistent child count that is updated incrementally as objects are added or removed. For very large containers (e.g., a “All Music” container with 50,000 items), the child count should be stored as a pre-computed value rather than computed on-the-fly. The Browse() action should also support the SortCriteria parameter for ordering child results, which requires indexed sorting to avoid performance degradation on large containers.

Frequently Asked Questions