Java 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 maven:

Add this to your pom.xml:

First, define the server to get the module from:

<repositories>
<repository>
<id>mediamachine-repo-snapshot</id>
<url>s3://maven-repo.mediamachine.io/snapshot</url>
</repository>
<repository>
<id>mediamachine-repo-release</id>
<url>s3://maven-repo.mediamachine.io/release</url>
</repository>
</repositories>

Second, add the S3 wagon as extension:

<build>
<extensions>
<extension>
<groupId>com.github.seahen</groupId>
<artifactId>maven-s3-wagon</artifactId>
<version>1.3.3</version>
</extension>
</extensions>
</build>

Third, as mediamachine client as a dependency

<dependencies>
<dependency>
<groupId>io.mediamachine</groupId>
<artifactId>mediamachine</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>

and then run:

$ mvn

Documentation#

If you want to get documentation for all the methods, you can always look at our javadoc.

Usage#

First create a mediamachine client:

import io.mediamachine.*;
final String MEDIAMACHINE_API_KEY = "your mediamachine api key here";
MediaMachine client = new MediaMachine(MEDIAMACHINE_API_KEY);

Each type of service (thumbnailJob(), summaryGifJob(), summaryMp4Job() and transcodeJob()) creates and returns a JobBuilder object that you can use to configure the Job.

Once you have your job configured you can call execute() to get a Job object that you can use to query the status of the job.

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

  • URL using from(String url)
  • Amazon S3 using fromS3(String region, String accessKey, String secretAccessKey, String bucket, String key)
  • Google GCP using fromGcp(String json, String bucket, String key)
  • Microsoft Azure buckets using fromAzure(String accountName, String accountKey, String bucket, String key)

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

  • Amazon S3 using toS3(String region, String accessKey, String secretAccessKey, String bucket, String key)
  • Google GCP using toGcp(String json, String bucket, String key)
  • Microsoft Azure buckets using toAzure(String accountName, String accountKey, String bucket, String key)
  • URL (We POST to that URL when the output is ready) using to(String url)

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.

thumbnailJob()#

The thumbnailJob() 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 returns a ThumbnailJob object which has the following methods to configure it:

  • width(Integer width) : number representing the desired width of the thumbnail (default: 720 px).
  • watermark(Watermark watermark) : a Watermark object to use for the image's watermark.
  • withTextWatermark(String text): configures the Watermark with default values and set the text provided to be used as watermark.
  • withImageWatermark(URL url): configures the Watermark with default values and set the image provided to be used as watermark.
  • withNamedWatermark(String imageName): configures the Watermark with default values and set the image stored in mediamachine provided to be used as watermark.
  • webhooks(Webhooks webhooks): a Webhook object to use to get the notified when a job is done.
  • execute(): Run the job, returning a Job object to query the status.

The simplest version might be:

Job job = client
.thumbnailJob()
.from("https://myserver.example/someVideo.mp4")
.to("https://myserver.example/api/uploadFile")
.execute();

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

Webhooks webhooks = Webhooks
.withDefaults()
.failureUrl("https://myserver.example/api/mediamachineFailure")
.successUrl("https://myserver.example/api/mediamachineSuccess");
Job job = client
.thumbnailJob()
.width(150)
.withTextWatermark("media machine!")
.webhooks(owebhooks)
.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
)
.execute();

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

Job job = client
.thumbnailJob()
.withTextWatermark("media machine!!!")
.fromAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, INPUT_KEY)
.toAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, OUTPUT_KEY)
.execute();

transcode#

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

This method returns a TranscodeJob object which has the following methods to configure it:

  • height(Integer height) : set the height of the output video.
  • width(Integer width) : set the width of the output video.
  • encoder(Encoder encoder) : Set the encoder to use on the output vide. Valid values are Encoder.h264, Encoder.h265, Encoder.vp8, Encoder.vp9.
  • container(Container container): Set the container to use on the output video. Valid values are Container.MP4 or Container.WEBM.
  • bitrate(BitrateKbps bitrate): Set the bitrate to use on the output vide. Valid values are BitrateKbps.FOUR_MBPS, BitrateKbps.TWO_MBPS or BitrateKbps.ONE_MBPS.
  • watermark(Watermark watermark) : a Watermark object to use for the image's watermark.
  • withTextWatermark(String text): configures the Watermark with default values and set the text provided to be used as watermark.
  • withImageWatermark(URL url): configures the Watermark with default values and set the image provided to be used as watermark.
  • withNamedWatermark(String imageName): configures the Watermark with default values and set the image stored in mediamachine provided to be used as watermark.
  • webhooks(Webhooks webhooks): a Webhook object to use to get the notified when a job is done.
  • execute(): Run the job, returning a Job object to query the status.

The simplest version might be:

import io.mediamachine.models.*;
const job = client
.transcode()
.container(Container.MP4)
.encoder(Encoder.h264)
.fromUrl("https://myserver.example/someVideo.avi")
.toUrl("https://myserver.example/api/uploadFile")
.execute();

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

import io.mediamachine.models.*;
Webhooks webhooks = Webhooks
.withDefaults()
.failureUrl("https://myserver.example/api/mediamachineFailure")
.successUrl("https://myserver.example/api/mediamachineSuccess");
const job = client
.trancode()
.width(150)
.height(150)
.encoder(Encoder.H265)
.container(Container.MP4)
.webhooks(webhooks)
.fromAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, INPUT_KEY)
.toAzure(ACCOUNT_KEY, ACCOUNT_NAME, BUCKET, OUTPUT_KEY)
.execute();

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:

import io.mediamachine.client.*;
const watermark = mediaMachine.textWatermark("media machine!!!", {
fontSize: 14,
fontColor: "#ffffff",
opacity: 0.9,
position: "bottomRight",
});
const job = client
.transcode()
.container(Container.WEBM)
.encoder(Encoder.VP8)
.withTextWatermark("media machine!!!")
.fromGCloud(GCLOUD_CREDS, BUCKET, INPUT_KEY)
.toGCloud(GCLOUD_CREDS, BUCKET, OUTPUT_KEY)
.execute();

summaryGifJob()#

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

This method returns a SummaryJob object which has the following methods to configure it:

  • width(Integer width) : set the width of the output video.
  • watermark(Watermark watermark) : a Watermark object to use for the image's watermark.
  • withTextWatermark(String text): configures the Watermark with default values and set the text provided to be used as watermark.
  • withImageWatermark(URL url): configures the Watermark with default values and set the image provided to be used as watermark.
  • withNamedWatermark(String imageName): configures the Watermark with default values and set the image stored in mediamachine provided to be used as watermark.
  • webhooks(Webhooks webhooks): a Webhook object to use to get the notified when a job is done.
  • execute(): Run the job, returning a Job object to query the status.

The simplest version might be:

const job = client
.summaryGifJob()
.fromUrl("https://myserver.example/someVideo.mp4")
.toUrl("https://myserver.example/api/uploadFile")
.execute();

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

import io.mediamachine.models.*;
Webhooks webhooks = Webhooks
.withDefaults()
.failureUrl("https://myserver.example/api/mediamachineFailure")
.successUrl("https://myserver.example/api/mediamachineSuccess");
const job = client
.summaryGifJob()
.width(150)
.withTextWatermark("media machine!!!")
.webhooks(webhooks)
.fromGCloud(GCLOUD_CREDS, BUCKET, INPUT_KEY)
.toGCloud(GCLOUD_CREDS, BUCKET, OUTPUT_KEY)
.execute();

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

import io.mediamachine.models.*;
const job = client
.summaryGifJob()
.withTextWatermark("media machine!!!")
.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
)
.execute();

summaryMp4Job()#

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

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

This method returns a SummaryJob object which has the following methods to configure it:

  • width(Integer width) : set the width of the output video.
  • removeAudio : a boolean to indicate whether to remove audio (default: false).
  • watermark(Watermark watermark) : a Watermark object to use for the image's watermark.
  • withTextWatermark(String text): configures the Watermark with default values and set the text provided to be used as watermark.
  • withImageWatermark(URL url): configures the Watermark with default values and set the image provided to be used as watermark.
  • withNamedWatermark(String imageName): configures the Watermark with default values and set the image stored in mediamachine provided to be used as watermark.
  • webhooks(Webhooks webhooks): a Webhook object to use to get the notified when a job is done.
  • execute(): Run the job, returning a Job object to query the status.

The simplest version might be:

const job = client
.summaryMp4Job()
.fromUrl("https://myserver.example/someVideo.mp4")
.toUrl("https://myserver.example/api/uploadFile")
.execute();

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.

import io.mediamachine.models.*;
Webhooks webhooks = Webhooks
.withDefaults()
.failureUrl("https://myserver.example/api/mediamachineFailure")
.successUrl("https://myserver.example/api/mediamachineSuccess");
const job = client
.summaryMp4Job()
.width(150)
.withTextWatermark("media machine!!!")
.removeAudio(true)
.webhooks(webhooks)
.fromGCloud(GCLOUD_CREDS, BUCKET, INPUT_KEY)
.toGCloud(GCLOUD_CREDS, BUCKET, OUTPUT_KEY)
.execute();

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

const job = client
.summaryMp4Job()
.withTextWatermark("media machine!!!")
.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
)
.execute();

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:

  • Status.IN_PROGRESS (The job is waiting to be executed).
  • Staus.DONE (The job has finished successfully)
  • Status.UNKNOWN (The job failed)

To get the status you can do:

job.status();

Watermarking#

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

You can configure watermarking for any/all of your summaryGifJob(), summaryMp4Job(), thumbnail() and transcode() calls by first creating a watermark, and then supplying it to the watermark() function.

There are two types of watermarks:

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

textWatermark#

The withTextWatermark(text) method takes a string of text to use. It will use all the default configuration:

  • fontSize: 12
  • fontColor: #000000
  • opacity: 1
  • position: bottomRight

imageWatermark#

There are two ways of adding an image watermark. You can provide an URL with a location of an image, or store an image with us and reference it by name.

The two main methods to use for this purpose are:

  • withImageWatermark(URL url): which is used to add a watermark provided from an url.
  • withNamedWatermark(String name): which is used to add a watermark image stored on mediamachine.

Both methods use the default configuration:

  • opacity: 1
  • position: bottomRight

Tweak Watermark options.#

If you want to use .watermark(Watermark watermark) and provide a custom Watermark (with custom configuration). You can instantiate one of the Watermark implementations:

  • WatermarkText
  • WatermarkImage
  • WatermerkNamedImage

Here's an example with all the options:

import io.mediamachine.models.*;
Watermark watermark = WatermarkText().withDefaults().text("media machine!!").fontSize(12).opacity(0.9).position(Position.BottomLeft).width(90);

Javadoc#

If you want to get documentation for all the methods, you can always look at our javadoc.