Back to top

RemasterMedia API implementation guide

This document describes recommended approaches and best practices of implementing RemasterMedia API v2.

API reference

For details on API resources and action refer to API reference document.

IMPORTANT NOTE

API reference document contains production API endpoint. You will receive another endpoint(s) for the development and testing.

Note on responses

Success responses will always have 2xx HTTP status code and the body will contain a JSON document with response data in the body.

Failure responses will always have 4xx HTTP status code and the body will contain a JSON document with error object.

Sample failed response:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "HTTP HEAD to source_url failed."
  }
}

Authentication

All API requests except the authentication itself must be authorized, so authentication must be performed first. To authenticate you will need your credentials: client_id and client_key. To perform authentication use /v2/auth resource (see API reference for details) with these credentials.

Successful authentication will produce JSON web token (JWT) that must be used to authorize all subsequent requests. It is recommended to cache JWT token on API client side using a store of your choice - in memory, Redis, database or even a file.

Workflow

General workflow

Basic workflow is:

  1. Authenticate
  2. Create new Mediafile
  3. Process the Mediafile by applying action
  4. Wait until the processing finishes
  5. Request Mediafile details
  6. Download Mediafile file
  7. Optionally repeat from step 3 with different action with either the originally uploaded file or continue with the newly processed Mediafile until satisfied with result

Create New Mediafile

To start processing media, first you must provide url of the file you want to process. The file is then analysed (check corruptness, detect codecs). After successful analysis you can start processing the Mediafile.

To create new Mediafile, you make a request to /v2/mediafiles/create (see API reference for details). The request includes following data:

  • File to be processed location (required) - There is no need and thus no way to upload your files. We will read them directly from your storage using HTTP protocol, so you will be submitting an URL (see more details on Source file URLs below).

  • Webhook address (optional) - If you specify a webhook when submitting we will send that webhook when initial analysis finishes.

  • Custom data (optional) - You can attach custom data which might be relevant for you, eg order id. You’ll receive them together with Mediafile details.

After submitting, media analysis immediately begins. Response contains newly created Mediafile object and it’s status which will be pending until the initial metadata analysis finishes. If analysis finishes successfully, status will change to success and the Mediafile’s metadata will be filled. If analysis fails, status will change to failed. Failed Mediafile cannot be processed.

If you provide webhook address, you’ll receive a webhook event when Mediafiles status changes.

Source file URLs

The only accepted protocols are http:// or https://. Besides that, the only requirement is that the file must be accessible to our systems using HEAD and GET HTTP methods. If these two conditions are not met, you will receive an error response when submitting a Mediafile.

Using URLs allows you to easily provide a file to RemasterMedia in various storage scenarios:

  • Public access to file

    There will be just a simple URL like: https://somecdn.com/filename.

  • One or limited time access to file

    Example is pre-signed URL with AWS S3. Then the URL will look like: https://remastermedia-data.s3-accelerate.amazonaws.com/filename-maxpresence?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIX54PW5OH2ZXKJAA%2F20191212%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20191212T174426Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=838e0f8f85f98251b0d0d1b812e8e69d5e57342f7c00d803fa7652fcb5836b7f

  • Basic HTTP Auth

    The URL will contain username and password: https://username:password@domain.com/filename

Actions

To apply an action on Mediafile choose the action and make a request to /v2/mediafiles/process with following data:

  • Mediafile ID (required) - ID of the Mediafile to process.

  • Action name (required) - Name of the processing action. See below.

  • Action options - Action may have some options. See each action for details.

  • Webhook address (optional) - Processing the action may take a long time (depending in clip length and action). If you specify a webhook when submitting we will send that webhook when the action finishes.

  • Custom data (optional) - You can attach custom data which might be relevant for you, eg order id. You’ll receive them together with Mediafile details.

Remaster

Getting presets

RemasterMedia contains set of pre-defined remastering presets that describe how to manipulate audio stream when remastering. To remaster the Mediafile you need to select one or more of these pre-defined presets. To get available presets use /v2/actions/remaster/presets (see API reference for details).

Presets are organized in categories such as Web or Mobile, Broadcast TV or Radio, Special Applications. It is up to you to present these categories or not to the users in your UI. Categories contain presets that have attributes:

  • name - Name is unique identifier of a preset. Use it to for every reference to a preset except displaying the preset to the users in UI. Note: preset name is used to identify remastered files more easily - name is attached as a suffix to a filename.

  • title - Human readable “name” of the preset. Display it in the UI instead of name.

  • description - Contains longer description of what the preset does.

The presets do not change often, but to minimize risk of any issue with missing/outdated presets it is recommended to get available presets every time when your application/feature is launched by the user.

If you use mobile SDKs that allow to preview presets directly on mobile device, you need to get preset definitions. To get a preset definition use definition_file attribute (see API reference for details) when getting the presets. You will find there an AWS S3 URL where you can download a preset definition you supply to libDPS using DPSLoadProfileFromFile function.

Recommended flow of handling remaster preset definitions is:

  1. Request all remastering presets. As a response you will get regular list of categories and presets as described above. Note updated_at attribute of a preset which contains last update timestamp.

  2. Depends on first or next use:

    • First use: Store remastering presets info into your app local storage and then go one by one and request preset download. Store preset files locally
    • Next uses: Compare last update time of what you received with your local storage. If there has been an update on something, request preset definition download on that particular preset and replace your local preset file (eg. sync with the server side).
  3. Provide updated presets to the user.

Wait for the action to finish

As a response to submitting a processing action you will get details of the newly created Mediafile with the action applied to it. You then need to wait until the processing finisihes (same as in initial analysis). You can then “poll” using /v2/mediafiles/{id} resource (see API reference for details) to check Mediafile’s status.

Action finished webhook

Recommended alternative to polling the details regularly is using a webhook. If webhook URL is provided when submitting Mediafile action we will send this webhook when that Mediafile action changes. The webhook will POST Mediafile details document:

{
  "created_at": "2021-09-01T12:34:45Z",
  "event": "action.success",
  "payload": {
    "mediafile": {
      "id": "53445",
      ...
    }
  }
}

Webhook doesn’t check the status code. So it doesn’t matter whether you respond with 2xx, 4xx or 5xx. After HTTP request succeeds, webhook is considered delivered and doesn’t try again.

Request Mediafile details

To request mediafile details at any time use /v2/mediafiles/{id} resource (see API reference for details).

Download processed file(s)

Each successfully processed Mediafile contains url you can use to download the file.

Example:

"mediafile": {
    "url": "https://remastermedia-data.s3-accelerate.amazonaws.com/filename-maxpresence?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIX54PW5OH2ZXKJAA%2F20191212%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20191212T174426Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=838e0f8f85f98251b0d0d1b812e8e69d5e57342f7c00d803fa7652fcb5836b7f",
    ...
  }

The location will be AWS S3 pre-signed GET URL you will use to download that file. Url expires after 1 day. Remind: ensure that the file is downloaded before it expires. Expiration is renewed with each new request.

Mediafiles collection

If necessary you can list mediafiles collection eg. mediafiles created between from and to time using /v2/mediafiles?from={from}&to={to} (see API reference for details). Be careful to set reasonable from and to so you will receive the response quickly.

Further questions

If you have any further questions regarding the implementation do not hesitate and contact us at info@remastermedia.com

Generated by aglio on 21 Sep 2021