Back to top

RemasterMedia API implementation guide

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

API reference

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

Note on responses

Success responses will always have 2xx HTTP status code and the body will contain either a JSON document with response data in the body or just binary data in octet stream.

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": "invalid_parameters",
    "message": "HTTP HEAD to source_file 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 /v1/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 of remastering a file is:

  1. Authenticate
  2. Get available profiles
  3. Submit a remaster of a file using selected profile(s)
  4. Wait until remastering is done
  5. Request remaster details
  6. Download remastered file

Getting profiles

RemasterMedia contains set of pre-defined mastering profiles that describe how to manipulate audio stream when remastering. To remaster your file you need to select one or more of these pre-defined profiles. To get available profiles use /v1/profiles resource (see API reference for details).

The profiles 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 profiles that have attributes:

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

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

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

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

Recommended flow of handling master profile definitions is:

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

  2. Depends on first or next use:

    • First use: Store mastering profiles info into your app local storage and then go one by one and request profile download. Store profile 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 profile definition download on that particular profile and replace your local profile file (eg. sync with the server side).
  3. Provide updated profiles to the user.

Submitting remaster

To remaster a file you need to submit a remaster using /v1/remasters resource (see API reference for details) with following data:

  • File to be remastered 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).

  • Profiles to remaster a file with (required) - You will use profile name(s) you got before.

  • Webhook address (optional) - The remastering may take a long time if source file is a long clip. If you specify a webhook when submitting we will send that webhook when remastering finishes. See more details below in Wait for remastering to finish chapter.

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

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 remaster.

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

Wait for remastering to finish

As a response to submitting a remaster you will get that particular remaster details you can request any time later using /v1/remasters/{id} resource (see API reference for details). Part of the data you receive is status object. It always contains three arrays:

  1. pending - Lists profile(s) that are waiting to be processed.
  2. success - Lists profile(s) that were successfully processed.
  3. failed - Lists profile(s) that failed during processing.

Initially as a response to submitting a remaster all profiles will be in pending state.

"status": {
  "pending": [
    {
      "profile": "maxpresence"
    },
    {
      "profile": "voicefocus"
    }
  ],
  "success": [],
  "failed": [],
}

You can then “poll” remaster details and easily measure if there are any profiles in pending array. If not remastering has finished.

Remastering finished webhook

Recommended alternative to polling the details regularly is using a webhook. If webhook URL is provided when submitting a remaster we will send this webhook when remastering finishes. The webhook will POST remaster details document:

{
  "remaster": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:16:22Z",
    "expires_at": "2020-02-08T02:16:22Z",
    "source_file": {
      "location": "https://s3_bucket.s3-accelerate.amazonaws.com/filename",
      "size": 3876112,
      "duration": 228,
      "type": "audio"
    },
    "status": {
      "pending": []
      "success": [
        {
          "profile": "maxpresence",
          "output_file": {
            "location": "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",
            "expires_at": "2020-02-08T02:16:22Z"
          }
        },
        {
          "profile": "voicefocus",
          "output_file": {
            "location": "https://remastermedia-data.s3-accelerate.amazonaws.com/filename-voicefocus?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",
            "expires_at": "2020-02-08T02:16:22Z"
          }
        }
      ],
      "failed": [],
    },
    "webhook": {
      "location": "https://domain.com/hook",
      "delivered": false
    }
  }
}

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.

Note: within the webhook you will receive false in remaster.webhook.delivered object. That is normal, because until webhook is successfully delivered the delivery state is false. Basically you can ignore this object when receiving a webhook.

Request remaster details

To request remaster details at any time use /v1/remasters/{id} resource (see API reference for details).

Download remastered file(s)

Once the remastering using a particular profile successfully finishes you will receive output_file object in remaster details response for that profile. Example:

"output_file": {
    "location": "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",
    "expires_at": "2020-01-08T02:15:15Z"
  }

The location will be AWS S3 pre-signed GET URL you will use to download that file. expires_at is a timestamp of pre-signed GET URL expiration time. Remind: ensure that the file is downloaded before it expires. Expiration is renewed with each new request.

Remaster collection

If necessary you can list remaster collection eg. remasters created between from and to time using /v1/remasters?from={from}&to={to} resource (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 27 Feb 2020