GeckoMediaPlugins

Gecko Media Plugins (GMPs)

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".

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* apiStruct,
                                size_t structSize);
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 with platform-appropriate line breaks. 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.1
Capability: encode-video, decode-video

The capability record lists strings used to identify APIs provided by the GMP.

How Gecko Loads a GMP

Gecko scans known locations either on disk or in the Windows registry for GMPs.

• Windows
  • 'Path' entry for child entries of registry entry 'Software\\MozillaPlugins' under 'ROOT_KEY_LOCAL_MACHINE'
• OS X
  • ~/Library/Internet Plugins/
  • /Library/Internet Plugins/
• Linux
  • /usr/lib/mozilla/plugins/

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:

content/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 on 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.