gistfile1.md

Preview Processor Registration Pattern

In order to make the Preview Processing a bit more maintainable, future proof and allow for easy 3rd party integration we need some sort of pluggable system that allows us to register new processors.

Each processor should register itself with the PP api so that it can be picked up and handed content items. Whenever a content item needs preview processing, all registered processors will be checked if they can handle the file. They should each return a number of how well suited they are to deal with the piece of content. The processor that returns the highest number will be chosen to generate the preview images.

We need a number rather than a boolean as this is not a binary decision. There might be some overlap between processors. ex: The following processors (and their order) are in the system:

• YouTube Processor (10)
• Default Link processor (0)

They are both able to handle content items that are links to a youtube file, but the YouTube processor is able to generate better thumbnails and fetch the title so it's prefered to the default link processor.

All the default OAE processors that we ship will return an order in the range [0, 10].

If a situation arises where a content item has 2 processors who express the same 'order' then the first will be picked and a warning will be logged.

Registration

Example for a 3rd party Kaltura module that contains a processor at processor.js and implements the below interface.

It would have the following in its init.js.

var PreviewProcessorAPI = require('oae-preview-processor');

var KalturaProcessor = require('./processor');

var init = module.exports.init = function(config, callback) {
    // Intialize the Kaltura processor
    KalturaProcessor.init(config);

    // Let the Preview Processor Engine know about this new kaltura PP.
    PreviewProcessorAPI.registerProcessor('kaltura', KalturaProcessor);
};

Preview Processor interface

A common interface that each PP should implement:

/**
 * This method gets called for _each_ content object that needs preview processing.
 * Each processor will get called and they should all return whether or not they can handle this type of file.
 *
 * @param  {PreviewContext}     ctx             The current preview context. It allows you to make requests to the app server to retrieve extra metadata
 * @param  {Content}            contentObj      The content object that needs processing
 * @param  {Function}           callback        Standard callback method.
 * @param  {Object}             callback.err    An error object (if any).
 * @param  {Number}             callback.order  A number that expresses how well suited this PP is to handle this piece of content. A negative number means this PP isn't able to deal with this piece of content. All default OAE processors return a number in the range [0, 10].
 */ 
var test = module.exports.test = function(ctx, contentObj, callback) {};

/**
 * Generates the actual preview images.
 *
 * @param  {PreviewContext}     ctx             The current preview context. It allows you to make requests to the app server to retrieve extra metadata
 * @param  {Content}            contentObj      The content object that needs processing
 * @param  {Function}           callback        Standard callback method.
 * @param  {Object}             callback.err    An error object (if any).
 */ 
var generatePreviews = module.exports.generatePreviews = function(ctx, contentObj, callback) {};

Example for Kaltura:

var VIDEO_MIME_TYPES = [ 'video/x-msvideo', 'video/x-dv', ... ];

var test = module.exports.test = function(ctx, contentObj, callback) {
    if (contentObj.resourceSubType === 'file' && VIDEO_MIME_TYPES.indexOf(contentObj.mime) !== -1) {
        // Use 100 as the 'order', as it is more well-suited to handle video files than any default OAE processor.
        callback(null, 100);
    }
};

var generatePreviews = module.exports.generatePreviews = function(ctx, contentObj, callback) {
    // Create signed download url
    var downloadUrl = '..';
    Kaltura.handle(downloadUrl, callback);
};

This looks fine to me, you might want to clarify If a situation arises where a content item has 2 processors who express the same 'order' then the first will be picked and a warning will be logged. to say if it's alphabetically first, or the first one registered, or indeterminate, etc.