Child pages
  • I02 API Concepts

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Media content on a media server can come with a huge list of associated metadata. To easily reference a specific media content item on a media server (or in a play queue) the client uses bookmarks. Bookmarks are the recommended way to reference and exchange position information and media items within the application. Bookmarks are NOT persistent and only designed for short-term use within the APIs. So an application can request a bookmark for a specific media item on a media server and tell the client to add this item to a play queue without the need to handle any actual metadata for this item. Bookmarks are basically strings but are opaque and shall not be manipulated by applications in any form.

All API calls are blocking calls. They only return after the request was completed. For all calls involving network access this can take relatively long time, several seconds are possible for a busy media server. Worst case is a time out (e.g. the target device is dead), taking up to a minute. Depending on the type of application this can create serious issues. If it's a headless application performing some background action, it might be irrelevant. For all UI-based applications this means most calls to the APIs need to be decoupled from the UI threads. A typical implementation would provide a request queue with callbacks on completion of the call. The application would implement some state machine on top of this, for example to show a spinning wheel while the request is being processed and allow to simply aborting it. Or in a UI automatically abort the request if the user selects to do something else.

By using the API a play queue for each media renderer in the network is automatically created. By using the bookmarks an application can add media items to a queue in one simple step without the need to handle a set of metadata. It's also possible to add media items to a play queue by setting all required metadata directly.