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.

Java SDK

Installation#

Documentation#

Usage#

thumbnailJob()#

transcode#

summaryGifJob()#

summaryMp4Job()#

Job#

Watermarking#

textWatermark#

imageWatermark#

Tweak Watermark options.#

Javadoc#

Product

Links

Company