Node SDK

This library will let you use MediaMachine's api to:

  • Transcode a video to a different format
  • Generate a thumbnail image from a video
  • Generate a summary from a video in gif or mp4 format

Installation#

Using npm:

$ npm install mediamachine

Using yarn:

$ yarn add mediamachine

Usage#

First import and create a mediamachine client:

import { MediaMachine } from "mediamachine";
const MEDIAMACHINE_API_KEY = "your mediamachine api key here";
const mediaMachine = new MediaMachine(MEDIAMACHINE_API_KEY);

Each type of request (thumbnail(), transcodeToMp4(), transcodeToWebm() and summary()) creates and returns a Job object that you can use to query the state of that Job.

Input for any of the services can come from any of the following:

  • URL using fromUrl()
  • Amazon S3 using fromS3()
  • Google GCP using fromGCloud()
  • Microsoft Azure buckets using fromAzure()

Also, each service type can store the output in any of the following:

  • Amazon S3 using toS3()
  • Google GCP using toGCloud()
  • Microsoft Azure buckets using toAzure()
  • URL (We POST to that URL when the output is ready) using toUrl()

Additionally, a request to any service can accept a success and failure endpoint, that will be called with the output of the process once it’s done.

thumbnail()#

The thumbnail() method uses a smart algorithm to automatically choose the best frame of a video, and additionally allows you to scale and watermark it.

This method takes a single argument of the following optional inputs:

  • width : number representing the desired width of the thumbnail (default: 720 px).
  • watermark : a Watermark object to use for the image's watermark.
  • successUrl : a url for MediaMachine to POST to when the thumbnail has been created.
  • failureUrl : a url for MediaMachine to POST to when the thumbnail could not be created.

The simplest version might be:

const job = await mediaMachine
.thumbnail()
.fromUrl("https://myserver.example/someVideo.mp4")
.toUrl("https://myserver.example/api/uploadFile");

Here's an example usage that takes a video from Amazon S3 and puts a thumbnail back to Amazon S3.

const job = await mediaMachine
.thumbnail({
width: 150,
watermark: mediaMachine.textWatermark("media machine!"),
successUrl: "https://myserver.example/api/mediamachineSuccess",
failureUrl: "https://myserver.example/api/mediamachineFailure",
})
.fromS3(
AWS_REGION,
AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY,
BUCKET,
INPUT_KEY
)
.toS3(
AWS_REGION,
AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY,
BUCKET,
OUTPUT_KEY
);

Here's an example usage that takes a video from Azure and puts a thumbnail back to Azure with a full watermark configuration:

const watermark = mediaMachine.textWatermark("media machine!!!", {
fontSize: 14,
fontColor: "#ffffff",
opacity: 0.9,
position: "bottomRight",
});
const job = await mediaMachine
.thumbnail({
watermark: watermark,
})
.fromAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, INPUT_KEY)
.toAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, OUTPUT_KEY);

transcodeToMp4()#

The transcodeToMp4() method transcodes SD/HD/FHD videos from virtually any format to Mp4.

This method takes a single argument of the following optional inputs:

  • height : number representing the desired height of the video output.
  • width : number representing the desired width of the video output.
  • watermark : a Watermark object to used for the image's watermark.
  • encoder : "h264", "h265", "vp8", "vp9" (default: "h264")
  • successUrl : a url for MediaMachine to POST to when the thumbnail has been created.
  • failureUrl : a url for MediaMachine to POST to when the thumbnail could not be created.

The simplest version might be:

const job = await mediaMachine
.transcodeToMp4()
.fromUrl("https://myserver.example/someVideo.avi")
.toUrl("https://myserver.example/api/uploadFile");

Here's an example usage that takes a video from Azure and puts an h265 mp4 version of it back to Azure.

const job = await mediaMachine
.transcodeToMp4({
width: 150,
height: 150,
encoder: "h265",
successUrl: "https://myserver.example/api/mediamachineSuccess",
failureUrl: "https://myserver.example/api/mediamachineFailure",
})
.fromAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, INPUT_KEY)
.toAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, OUTPUT_KEY);

Here's an example usage that takes a video from Google Cloud and puts an mp4 video back to Google Cloud with a full watermark configuration:

const watermark = mediaMachine.textWatermark("media machine!!!", {
fontSize: 14,
fontColor: "#ffffff",
opacity: 0.9,
position: "bottomRight",
});
const job = await mediaMachine
.transcodeToWebm({
watermark: watermark,
})
.fromGCloud(GCLOUD_CREDS, BUCKET, INPUT_KEY)
.toGCloud(GCLOUD_CREDS, BUCKET, OUTPUT_KEY);

transcodeToWebm()#

The transcodeToWebm() method transcodes SD/HD/FHD videos from virtually any format to Webm.

This method takes a single argument of the following optional inputs:

  • height : number representing the desired height of the video output.
  • width : number representing the desired width of the video output.
  • watermark : a Watermark object to used for the image's watermark.
  • encoder : "vp8", "vp9" (default: "vp8")
  • successUrl : a url for MediaMachine to POST to when the thumbnail has been created.
  • failureUrl : a url for MediaMachine to POST to when the thumbnail could not be created.

The simplest version might be:

const job = await mediaMachine
.transcodeToWebm()
.fromUrl("https://myserver.example/someVideo.avi")
.toUrl("https://myserver.example/api/uploadFile");

Here's an example usage that takes a video from Azure and puts a vp9 webm version of it back to Azure.

const job = await mediaMachine
.transcodeToWebm({
width: 150,
height: 150,
encoder: "vp9",
successUrl: "https://myserver.example/api/mediamachineSuccess",
failureUrl: "https://myserver.example/api/mediamachineFailure",
})
.fromAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, INPUT_KEY)
.toAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, OUTPUT_KEY);

Here's an example usage that takes a video from Google Cloud and puts a webm version back to Google Cloud with a full watermark configuration:

const watermark = mediaMachine.textWatermark("media machine!!!", {
fontSize: 14,
fontColor: "#ffffff",
opacity: 0.9,
position: "bottomRight",
});
const job = await mediaMachine
.transcodeToWebm({
watermark: watermark,
})
.fromGCloud(GCLOUD_CREDS, BUCKET, INPUT_KEY)
.toGCloud(GCLOUD_CREDS, BUCKET, OUTPUT_KEY);

summary()#

The summary() method creates a shorter summary/preview of the input video in GIF or MP4 format.

Note: For MP4 video summary, the input video should be more than 15 seconds long.

This method takes a single argument of the following optional inputs:

  • width : number representing the desired width of the video output.
  • watermark : a Watermark object to use for the image's watermark.
  • format : "mp4", "gif" -- the output format you want (default: "gif")
  • removeAudio : a boolean to indicate whether to remove audio (default: false, applies only to mp4s)
  • successUrl : a url for MediaMachine to POST to when the thumbnail has been created.
  • failureUrl : a url for MediaMachine to POST to when the thumbnail could not be created.

The simplest version might be:

const job = await mediaMachine
.summary()
.fromUrl("https://myserver.example/someVideo.mp4")
.toUrl("https://myserver.example/api/uploadFile");

Here's an example usage that takes a video from Google Cloud and puts a silent summarized mp4 version of it back to Google Cloud.

const job = await mediaMachine
.summary({
width: 150,
watermark: mediaMachine.textWatermark("media machine!"),
format: "mp4",
removeAudio: true,
successUrl: "https://myserver.example/api/mediamachineSuccess",
failureUrl: "https://myserver.example/api/mediamachineFailure",
})
.fromGCloud(GCLOUD_CREDS, BUCKET, INPUT_KEY)
.toGCloud(GCLOUD_CREDS, BUCKET, OUTPUT_KEY);

Here's an example usage that takes a video from Amazon S3 and puts a summarized gif back to Amazon S3 with a full watermark configuration:

const watermark = mediaMachine.textWatermark("media machine!!!", {
fontSize: 14,
fontColor: "#ffffff",
opacity: 0.9,
position: "bottomRight",
});
const job = await mediaMachine
.summary({
watermark: watermark,
})
.fromS3(
AWS_REGION,
AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY,
BUCKET,
INPUT_KEY
)
.toS3(
AWS_REGION,
AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY,
BUCKET,
OUTPUT_KEY
);

Job#

A Job object is what's ultimately returned from your request. You can query the job's status at any time with the status() method.

The possible states for the job are:

  • notStarted (The job has not been started at all).
  • queued (The job is waiting to be executed).
  • done (The job has finished successfully)
  • errored (The job failed)

To get the status you can do:

await job.status();

Watermarking#

A watermark is an image that is laid over another image or video, usually to add branding to it.

You can configure watermarking for any/all of your summary(), thumbnail(), transcodeToMp4(), and transcodeToWebm() calls by first creating a watermark, and then supplying it in the optional arguments to summary(), thumbnail(), transcodeToWebm() or transcodeToMp4() as the watermark parameter.

There are two types of watermarks:

  • text watermarks where you supply and configure some text to be the watermark. ( see [textWatermark()](#textWatermark(text, [options])) )
  • image watermarks where you supply and configure an image to be the watermark ( see imageWatermark() ).

textWatermark(text, [options])#

The textWatermark(text, [options]) method takes a string of text to use as well as an additional argument of the following optional inputs:

  • fontSize : the size for the text (a number, default: 12)
  • fontColor : the color for the text ( default: "#000000")
  • opacity : number between 0 and 1 representing the desired opacity of the output. 0 is full transparent and 1 is fully opaque (default: 1)
  • position : "topLeft", "topRight", "bottomLeft", "bottomRight" (default: "bottomRight")

The most simple example is probably:

const watermark = mediaMachine.textWatermark("media machine!!!");

Here's a more complex example using all the options:

const watermark = mediaMachine.textWatermark("media machine!!!", {
fontSize: 14,
fontColor: "#ffffff",
opacity: 0.9,
position: "bottomRight",
});

imageWatermark()#

The imageWatermark() method takes a single argument of the following optional inputs:

  • url : the url of the image to be used
  • uploaded_image_name : the name of the uploaded image to be used
  • width : number representing the desired width of the video output
  • height : number representing the desired height of the video output
  • opacity : number between 0 and 1 representing the desired opacity of the output. 0 is full transparent and 1 is fully opaque (default: 1)
  • position : "topLeft", "topRight", "bottomLeft", "bottomRight" (default: "bottomRight")

NB: You must supply uploaded_image_name or url, but not both.

Here's a simple example using a url:

const watermark = mediaMachine.imageWatermark({
url: "https://myserver.example/asdf.jpg",
});

Here's another simple example using a named watermark, after you upload one to our servers:

const watermark = mediaMachine.imageWatermark({
uploaded_image_name: "company_watermark",
});

Here's an example with all the options:

const watermark = mediaMachine.imageWatermark({
uploaded_image_name: "company_watermark",
position: "bottomLeft",
height: 40,
width: 90,
opacity: 0.9,
});
MediaMachine
twitter icongithub icon

Product

Links

Company

© 2020-2021. All rights reserved.