Developers handbook

Engines, events and conditions can be implemented as plugins. Here is the basic API explanation.

Engines

Engines are really simple. Module that wants to be an engine, should first implement a simple info hook, that returns an array containing info about engine's capabilities:

function hook_media_derivatives_engine_info() {
  return array(
    'type' => 'video',
    'stream_wrappers' => array('public://', 'private://'),
    'mime_types' => array('video/mp4', 'audio/*'),
  );
}

• type: type of files, that can be derivated using this engine,
• stream_wrappers: array of stream schemas, that this engine know how to deal with (optional),
• mime_types: array of mime types, that this engine know how to deal with (optional), wildcard '*' can be used.

There is also hook_media_derivatives_engine_info_alter() available. Derivation callback should be implemented, when Drupal knows about the engine:

function hook_media_derivatives_create_derivative($file, $derivative) {
  // Create derivative of a $file. Configuration preset is saved in $derivative.
 
  return $new_file;
}

This function is expected to return derivative's URI or a full file object. API will build file object, if only URI is returned. There is also an example implementation.

Conditions

Module that wants to implement a conditon, should implement info hook:

function hook_media_derivatives_conditions_info() {
  $conditions = array();
  $conditions['example_rule'] = array(
    'name' => t('Example derivation rule'),
    'description' => t('In-depth description of example rule'),
    'callback' => 'mymodule_myrule_callback',
  );
  return $conditions;
}

There is also hook_media_derivatives_conditions_info_alter() available. Info hook should return array of conditions implemented by this module, with each element's key being a condition's machine name and value an array with human readable name, description and name of callback function. API will call this function when a condition needs to be tested. Callback function is expected to return TRUE or FALSE. File will only be processed if if all active conditions return TRUE. Source file and configuration preset will be passed to callback function. Here is a simple example of a condition callback function:

function media_derivatives_type_support($file, $preset) {
  return $file->type == $preset->rules_settings['type'];
}

There is also an example implementation

Events

Info hook should be implemented to inform system about a new event:

function hook_media_derivatives_events_info() {
  $events = array();
  $events['file_insert'] = array(
    'name' => t('File insert derivative event'),
    'description' => t('Derivative event, that will be executed when a new file is saved.'),
    'validation_callbacks' => array(
      '_media_derivatives_file_insert_validation'
    ),
  );
  return $events;
}

There is, once again, hook_media_derivatives_events_info_alter() available. Info hook is mostly self-explanatory. Only part, that probably needs some more attention, are optional validation functions. Names of validation callbacks should be passed in that array. Callback functions are going to be called before a derivative will be created. Validation function should return TRUE if a file should really be derivated or FALSE, if a derivation process of a given file, triggered by this event, should be canceled. Validation callback will get file, configuration preset and context information as arguments. Example of validation callback:

function _media_derivatives_field_presave_validation($file, $preset, $context) {
  return in_array(
    $context['field'], 
    $preset->triggers_settings['field_presave_allowed_fields']
  );
}

Module should call media_derivatives_create_all_derivatives() or media_derivatives_create_derivative(), when an event is to be triggered. First function will take a file and try to create derivatives for all active presets in the system, while second will take preset as an argument and create a derivative just for that preset.

// Some code ...
media_derivatives_create_all_derivatives($file, $trigger, $context);
// Or just for a single preset
media_derivatives_create_derivative($file, $preset, $trigger, $context);

• $file: source file file object,
• $trigger: event's machine name as passed to info hook,
• $context: context information, that will be passed to the validation callback,
• $preset: configuration preset, that is to be used for this derivation process.

There is also an example implementation

Schedulers

To be documented.... In the meanwhile please see example implementation.