Custom Metadata Providers for Media Files

This topic describes how to write a custom Shell property handler for a Microsoft Media Foundation media source.

Metadata is closely tied to the format of the file. In Media Foundation, file formats are represented by media sources. If you want to support metadata for a format that is not supported natively in Media Foundation, you must implement a custom media source with a property handler. The property handler enables the Shell property system to read and write metadata efficiently.

A property handler is a COM object that implements the following interfaces:

• IInitializeWithStream
• IPropertyStore

Optionally, it can also expose the following interface:

• IPropertyStoreCapabilities

If the Shell property system needs to get metadata for a file, it calls CoCreateInstance to create the property handler and then calls the appropriate read and write methods on the IPropertyStore interface.

The Media Foundation pipeline uses a slightly different mechanism, because the pipeline gets the property handler directly from the media source. Instead of calling CoCreateInstance to create the property handler, the pipeline calls IMFGetService::GetService on the media source, as described in the topic Shell Metadata Providers.

To create a custom property handler, do the following:

• Implement the IMFGetService interface to expose IPropertyStore. The service GUID is MF_PROPERTY_HANDLER_SERVICE.
• If the media source will be used remotely, it must also expose the IPropertyStore interface through the media source's QueryInterface method, in addition to IMFGetService.
• To make the property handler available to the Shell property system, register the DLL for the property handler as described in Registering and Distributing Property Handlers.
• The media source is registered separately, as described in Scheme Handlers and Byte-Stream Handlers.

Implementation Tips

For a list of metadata property keys, see Metadata Properties for Media Files.

Property handlers must be fast; they must provide efficient read and write access to the metadata. (Consider that the Shell may retrieve metadata from hundreds of files.) Therefore, do not call MFStartup from your property handler. The MFStartup function introduces startup latency, because it creates multiple work-queue threads and allocates global memory.

In a typical implementation, the property handler and the media source will share some of the same parsing code. However, a media source uses asynchronous IMFByteStream calls for I/O, whereas the property handler uses the IStream interface. Media Foundation provides a helper object that wraps an IStream-based stream and exposes it as an IMFByteStream stream. To create the wrapper, call MFCreateMFByteStreamOnStream.

When updating metadata, it is recommended to write the data directly to the original stream. This recommendation differs from the copy-on-write behavior of most property handlers, in which a copy of the data is modified. Media files can be very large, so copy-on-write is typically too slow for an efficient implementation. To disable copy-on-write, set the ManualSafeSave registry setting, as described in Registering and Distributing Property Handlers.

Related topics

Media Metadata

Media Sources

Writing a Custom Media Source