Redirect Notice

This turorial page shows:

• How to use media tranforms to customize media objects before the playback starts.
• How to use media tranforms when asynchronous processing is required.
• How to prioritize transforms by using the akamai.amp.Transform interface.
• How to use cascading transforms.
  
  

Using media tranforms to customize media objects

Sometimes there is a need to alter a media item before beginning playback. Some examples of this could be:

• Request an authorization token to append to the stream url
• A server side ad service which accepts some parameters then returns a dynamically generated stream url
• A feed is provided by a third party service which does not match AMP's Media interface akamai.amp.Media

A media transform can be any function that accepts a media object, and returns a media object. In the next fictional example we need to add an extra argument.

// synchronous transform
amp.addTransform(akamai.amp.TransformType.MEDIA, function (media)
  // We're appending some token we need to the url
  media.src += "&someExtraArgument=1234";
  return media;
});

Using media tranforms for asynchronous processes

A Promise can be returned if the transform performs any asynchronous operation. The promise must return a media object when resolved. Using again our previous example, let's asume we need to obtain the given extra argument asynchronously.

// asynchronous transform
amp.addTransform(akamai.amp.TransformType.MEDIA, function (media) {
  // A promise that will resolve with a media object
  return new Promise(function (resolve, reject) {
    /*
    Code to get asynchronous data we need
    */
    let asyncArg = await getExtraArgAsynchronously();
    media.src += "&someExtraArgument=asyncArg";
    resolve(media);
  });
});

Prioritizing Transforms Using akamai.amp.Transform

In the case that transform execution must be prioritized as well as some other advanced scenarios a formal transform object can be provided. The transform object must follow the akamai.amp.Transform interface. Put simply, this can be any object that contains a property called transform which is a function. In order to prioritize the transform execution the property priority should also be included. Transforms with higher priorities are executed first.

// asynchronous transform
amp.addTransform(akamai.amp.TransformType.MEDIA, {
  priority: 100,
  transform: function (media) {
    return new Promise(function (resolve, reject) {
      media.src += "&hello=world";
      resolve(media);
    });
  }
});

Cascading Transforms

Functions used as transforms cascade. This allow transformations to occur on both the downstream and upstream. Calling the next() function suspends the transform and passes control to the next function in the list. When the other transforms have completed, the function resumes.

// cascading transform
amp.addTransform(akamai.amp.TransformType.MEDIA, function (media, next) {
  return new Promise(function (resolve, reject) {
    var start = Date.now()
    // allow other transforms to be executed before completing this function
    next(media)
      .then(function (result) {
        result.src += "&elapsed=" + (Date.now() - start);
        resolve(result);
      })
  });
});