Gecko Media Plugins (GMPs)

Purpose

GMP is a special purpose extension point for authorised 3rd party codecs and EME (Encrypted Media Extensions) CDMs (Content Decryption Modules).

On Disk Layout

GMPs consist of a directory on disk containing two files, at a minimum: a dynamic library and a meta-data file.

The plugin directory name must start with "gmp-", and the rest of the name will be considered the plugin's "base name." For example - "gmp-foobar" has a base name of "foobar".

The dynamic library's name must be the plugin's base name surrounded by platform conventions for a dynamic library. Given our "foobar" example, this would be "libfoobar.dylib" on OS X, "foobar.dll" on Windows, and "libfoobar.so" on Linux.

The plugin meta-data file is a UTF-8 text file named with ".info" after the plugin base name. Given our "foobar" example, this would be "foobar.info".

For example, for a gmp-foobar plugin, the disk layout on Windows for version "1" would be:

gmp-foobar/
gmp-foobar/1
gmp-foobar/1/foobar.dll
gmp-foobar/1/foobar.info

The Dynamic Library

The main dynamic library needs to expose three C functions publicly:

• GMPInit
• GMPGetAPI
• GMPShutdown

The types for these functions are:

typedef GMPErr (*GMPInitFunc)(void);
typedef GMPErr (*GMPGetAPIFunc)(const char* apiName,
                                void* aHostAPI,
                                void** aPluginAPI);
typedef void   (*GMPShutdownFunc)(void);

See the Base API section for more information.

The Meta-Data File

GMP meta data is stored in a UTF-8 text file. Each line is a record. Name, description, version, and capability records are required, in order. An example:

Name: MyCompany h.264 Plugin
Description: Provides encoding and decoding of h.264 video.
Version: 2
APIs: encode-video[h264], decode-video[h264]

The capability record lists strings used to identify APIs provided by the GMP. Each API can (optionally) have a list of tags associated with it, giving further information about what is supported. The separator character for the list of tags is ":" (e.g. "[aFormat:bFormat:cFormat]"). In this example the plugin is stating that it can operate on "h264" video, which is understood by Gecko. This allows Gecko to know what formats are supported without loading the plugin.

The "Version" field must be a whole non-negative integer value. For EME GMPs, the version of plugin can be requested in the keySystem string when requesting access to the MediaKeys from JavaScript. For example, to ensure you have version 1 of the ClearKey CDM, from JavaScript call navigator.requestMediaKeySystemAccess("org.w3.clearkey.1", ...).

How Gecko Loads a GMP

Firefox addons and the Firefox addon manager tells Gecko where to look for plugins, using the mozIGeckoMediaPluginService.addPluginDirectory and .removePluginDirectory API.

Developers prototyping new addons may also use the environment variable MOZ_GMP_PATH to specify a list of directories. Note that the paths set in MOZ_GMP_PATH must still conform to the rules in "On Disk Layout" above, i.e. the path points to the "version" subdirectory, which has a parent directory whose name has a "gmp-" prefix. i.e. MOZ_GMP_PATH=/home/username/src/gmp-foobar/1/.

It maintains a list of known GMPs, and when an API is requested by a consumer it scans the list for a GMP that can provide the API.

Gecko will then spin up a child process for the GMP. GMPs can only be loaded out-of-process, there is no in-process option. Furthermore, child processes may be sandboxed, so GMPs cannot depend on being able to do things outside of the sandbox (like write to disk).

The child process will load the GMP's DLL into the process, then call the publicly exposed GMPInit function. Next Gecko will call the publicly exposed GMPGetAPI function, requesting the desired API data (see the Base API section for more info).

At this point Gecko and the GMP will start doing actual work via the information in the API object. When all consumers are done with the GMP, Gecko will call the publicly exposed GMPShutdown function before closing the child process.

Base API

There is a base Gecko Media Plugin API that allows more specific APIs to be requested. The API is described in code by the text file located at:

dom/media/gmp/gmp-api

in any copy of the Gecko source code that includes GMP support. GMPGetAPI returns a void pointer which can be cast to the structure defined for any specific API, such as video encoding or decoding.

Memory for the structure is allocated by the host, and the size of that allocation is passed in as well. In part this is done to allow the host to decide how to allocate memory. Perhaps more importantly though, this allows the host to fill in parts of the structure before passing it to the GMP. An example would be the host passing callback function pointers to the GMP. This behavior should be specified clearly in any API specification.

Process Model

Gecko will create one process per origin, with an origin's process handling of all of its resources. This may change in the future.