Writing Custom Playlist providers

providersample.zipprovidersample.zipThe idea of this blog is to show the extensibility model of the Web Playlists feature. 

The playlist  feature consits of two indepdent components that communicate via a well defined API boundary

1. A playlist handler - That handles all the playlist requests. The handler is a reqular IIS request handler and maps certain known extensions as playlists. It is responsible for rendering the playlist into an ASX output, managing the session and processing the individual entries in the playlist.
2. One or more playlist providers - A provider is a standalone COM component that provides the actual playlist information.  Each provider is registered to handle requests for one file extension (though you could register your provider for multiple extensions) .  The handler asks the provider for the playlist information and then uses it to render playlist and process the entries in the playlist. 

 The handler access the provider via COM interface though the actual provider implementation can be done in COM (VC++, VB) or managed code (C#, VB.Net).  To understand this further let me illustrate a sample provider that works as a wrapper playlist generator.  The idea of wrapper playlist is to wrap each requested video file with an advertisement (which cannot be skipped/seeked).  For example you webpage has a video called tutorial.wmv.  You need to reigster your provider for a unique extension (say .wpl)  and your webpage needs to be updated to refer tutorial.wpl.  When the user opens this link, the handler will send an ASX file with two entries (first a predefined adverstiment) and then the actual video.

If you are wondering why you need a separate file extension for playlist (and not re-use the original file extension) then, that is due to support for nested playlists. If the playlist is called a.wmv and the entry in the playlist is  b.wmv the handler decides wether it is a regular entry or nested palylist based on the extension. If you think it is a bit of pain to update the URLs in your pages you could write an additional IIS module to rewrite the URLs (or wait for the upcoming IIS re-write module :-) )

Implementing a playlist provider is very straight forward. You implement a COM Component that implements IPlaylistProvider interface.  The interface needs to implement just 3 methods

• Initialize - Called when the provider is loaded (on the first request). A place holder for one time initialization
• Shutdown - Called when the IIS worker process is going down. A Place holder for resource cleanup.
• GetPlaylistInfo - The real logic lies in this method that maps a request to a playlist object.  The provider returns a IPlaylistInfo object that describes a playlist. The Playlist handler uses the IPlaylistInfo object returned by the provider to render the response as well as validate the individual entries in the playlist. Below is code from sample provider:

         IPlaylistInfo IPlaylistProvider.GetPlaylistInfo(IPlaylistRequestInfo requestInfo)
        {
            String path = requestInfo.Path;
            String name = path.Substring(path.LastIndexOf('/') + 1);
            name = name.Substring(0, name.LastIndexOf(".")) + ".wmv";
            return new PlaylistInfo(Advertisement, name);
        }

The logis is just replacing .wpl with .wmv though the actaul media file could .flv or .mp4 or any other valid media file format.

The IPlaylistRequestInfo passed to the provoider is a simple COM wrapper on top of IHttpContext and exposes some of the useful underlying information.  The Path property for example give the path of the request URL (/tutorial.wpl in this case). The IPlaylistRequestInfo has methods to Get/Set a server variable (and thus interact with other IIS modules) and also a way to store/retrieve session state ( in a String form).

The IPlaylistInfo is an interface to describe the palylist. You need to create an object impleting this interface. The IPlaylistInfo has the following methods that need to be implemented

• GetProperty - Return properties of the playlist like title, copyright, timeout etc
• Entries - Return a IPlaylistEntryInfoCollection object to enumerate over the entries in the playlist.

The next interface to be implemented is the IPlaylistEntryInfoCollection. It just has two propetries 

• Count - the no. of entries in the playlsit and 
• Item - the information about the actual entry.

The next interface that needs to be implemented is the IPlaylistEntryInfo interface. You need to return an object of this interface for each entry in the playlist. This interface has the following methods

• GetProperty - The properties of this entry i.e wether user can seek/skip forward/skip backward, title etc.
• EntryType - An enumeration on how the actual media file is located i.e physical path, relative path, remote URL etc
• Uri - The actual location of the media file. If the path is a realtive path then the Playlist handler with do the mapping from relative to absolute path before returning the file and you don't have to bother about the directory structrue and other details.

You need to know some points about the contract between the handler and the provider

1. For a playlist you cannot change the no. of entries in the playlist after the initial request. This is because there is no way to change the ASX sent already to the client.  Though the actual file returned for each playlist can be changed with each call.  However if the same playlist is requested again (by same or different user) then no. of entries need not be the same.
2. If you want a dynamic playlist with unlimited no. of entries you can use nested playlists
3. For nested playlists the Path property of the IPlaylistRequestInfo object will point to the nested playlist (And that should be used instead of relying on the SCRIPT_NAME server variable)
4. The IPlaylistFileInfo object is available on when the actual playlist is a physical file on disk and the handler is registered as a file handler. 

The zip below contains the sample code (implemented both as managed/COM provider). The solution file included is for Visual Studio 2008 though the source code should work on Visual studio 2005 as well. To  use the sample you need to copy the playlisthandler.dll from the playlist install to the directory where the solution file (.sln) is present. The file is under %PROGRAMFILES%\IIS\Media on an installed machine.

providersample.zip (The samples in this blog are provided as is with no warranties, and confer no rights. The views expressed in this blog are entirely my own and not of my employer. I currently work for Microsoft)