Back to top

RemasterMedia

RemasterMedia is a sound processing service. It takes media files (audio/video) on the input, applies audio effects like remastering using pre-defined presets, to create media file with improved sound at the output.

IMPORTANT NOTE

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

Authentication And Authorization

All API requests except the authentication must be authorized, so authentication must be performed first. Successful authentication will produce JSON web token (JWT) that must be used to authorize all subsequent requests.

Authentication

Performs authentication using provided credentials.

Authenticate
POST/auth

Example URI

POST https://api.remastermedia.com/v2/auth
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "client_id": "34198c6e05300a7f8b7a",
  "client_key": "629+fmypnpAM0GV52z+7EG25d+rUpQ3lYADf5lAM"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "Client ID in form of hash."
    },
    "client_key": {
      "type": "string",
      "description": "Client key in form of hash."
    }
  },
  "required": [
    "client_id",
    "client_key"
  ]
}
Response  200
HideShow

Authentication token and its validity

Headers
Content-Type: application/json
Body
{
  "auth": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfaWQiOiJxd2UiLCJleHBpcmF0aW9uIjoiMjAyMC0wMi0yNVQxNToxMjozNloifQ.M6EIX7FYOH9Ibtof6yVzS5uTopzeL6IARxqok4z4qZ5",
    "expires_at": "2020-02-08T02:16:22Z"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth": {
      "type": "object",
      "properties": {
        "token": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow

Request body is malformed.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "bad_request",
    "message": "Required param is missing or the value is empty: client_id."
  }
}
Response  401
HideShow

Authentication failed because of invalid client_id/client_key combination.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Authenticatioin failed. Invalid client_id/client_key combination."
  }
}

Mediafiles

Mediafiles are central entities in RemasterMedia API. Each represents an audio or video file that has its location (defined by HTTP URI) where it can be accessed and downloaded from. Remind: when we receive a request to process a file we check the access to the file using HTTP HEAD method. If this is not successful it will generate failure repsonse. Then an processing action (such as remastering using a profile)s can be applied to such file. The action will generate a new file with the output of that action. Other actions can be applied to that newly created file.

The way you use Mediafiles depends on whether you would like to apply an action to a new file or a file that is an output of previous action eg. existing file.

  • New file - When it is a new file you have to create a new Mediafile by providing it’s url and wait until the initial file analysis finishes. That analysis will give you the information whether we can process that file and detected metadata (when analysis succedes) or the information what is wrong with that file and we cannot process it further (if analysis fails). Then you select which action you want to perform on that Mediafile and apply it to the files.

  • Existing file - When using already existing file that was genereated by previous action(s), you can simply select which other action you want to perform on that Mediafile and apply it to the files.

Create New Mediafile

To create a new Mediafiles, first you must provide the source url and let the us to analyse it. Optionally yout can provide a webhook url where we send a webhook when the analysis is finished plus some user data.

Create New Mediafile
POST/mediafiles/create

After submitting a Mediafile, it will have status pending for a while until the initial analysis is finished. When that’s done, you can check Mediafile’s details and apply actions to it. If you specify a webhook_url, we will send a web hhook to that URL when the analysis finishes.

Parameters:

  • source_url - Location of media file in form of URL. (string, required)

  • webhook_url - Address where the webhook will be sent when initial media analysis finishes. (string, optional)

  • user_data - Custom user data that will be stored along with the Mediafile and returned when reading the Mediafile. An option to add some context. (object, optional)

Example URI

POST https://api.remastermedia.com/v2/mediafiles/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Body
{
  "webhook_url": "https://name.example.com/hook",
  "user_data": {
    "order_id": "1234"
  },
  "source_url": "https://name.example.com/path/filename"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "webhook_url": {
      "type": "string",
      "description": "Address where the webhook will be sent when initial media analysis finishes"
    },
    "user_data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        }
      },
      "description": "Custom user data that will be stored along with the Mediafile and returned when reading the Mediafile. An option to add some context."
    },
    "source_url": {
      "type": "string",
      "description": "Location of media file in form of URL."
    }
  },
  "required": [
    "source_url"
  ]
}
Response  201
HideShow

Media file created successfully.

Headers
Content-Type: application/json
Body
{
  "mediafile": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "analysis",
    "status": "pending",
    "options": {},
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string"
            }
          }
        },
        "action": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "options": {
          "type": "object",
          "properties": {}
        },
        "webhook_url": {
          "type": "string"
        },
        "user_data": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "created_at",
        "updated_at",
        "expires_at",
        "url",
        "metadata",
        "action",
        "status",
        "options",
        "webhook_url",
        "user_data"
      ],
      "additionalProperties": false
    }
  }
}
Response  400
HideShow

Request body is malformed.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "bad_request",
    "message": "Required param is missing or the value is empty: source_url."
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  422
HideShow

File is unreachable

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unprocessable_entity",
    "message": "File at source_url is unreachable."
  }
}

Process Mediafile

To apply an action to a Mediafile send a POST request with a body in a following format:

{
    "action": "remaster",
    "mediafile_id": "12345",
    "webhook_url": "https://example.com/hook",
    "user_data": {
      "order_id": 87687
    }
  }

where:

  • action (string, required) Name of the action to perform. See bellow,

  • mediafile_id (string, required) ID of the Mediafile to use as an input.

  • webhook_url (string, optional) Address where a webhook will be sent when the media processing finishes,

  • user_data (object, optional) Custom data object that will be stored along with the Mediafile and returned when reading the Mediafile details.

  • options (object) Action specific options, see action details possible values.

Note: In order to start processing Mediafile it must be in success status after the initial analysis has finished else you receive unprocessable entity error response.

Available actions

The actions are processed that can be applied to a Mediafile. Currently available actions are:

  • Remastering

  • Creating waveform

  • Creating video poster

  • Denoise

There may be more actions available later, so ask if unsure.

Create Remaster
POST/mediafiles/process

Creates remastered Mediafile. Remastered Mediafiles have improved or in other way modified audio stream. To start remastering you must provide name of the remastering preset. To list presets see List remastering presets.

There is an option to use HTML5 compatible format for the output media which will convert the output media audio to 320kbps MP3 and video to 800kbps H264 MP4 with resolution scaled down to 640x480 pixels.

Options:

  • preset - Preset name. (string, required)

  • offset - Skip first number seconds fro Mediafile. If not set the processing will start from the beginning of the Mediafile. (number, optional)

  • duration - Limit length of the output in seconds. If not set the processing will take everything till the end of the Mediafile (number, optional)

  • html5_compatible - Create output in HTML5 compatible codec/format (boolean, optional)

Example URI

POST https://api.remastermedia.com/v2/mediafiles/process
Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Body
{
  "webhook_url": "https://name.example.com/hook",
  "user_data": {
    "order_id": "1234"
  },
  "source_id": "56323",
  "action": "remaster",
  "options": {
    "preset": "max_presence",
    "duration": 90,
    "offset": 10,
    "html5_compatible": false
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "webhook_url": {
      "type": "string",
      "description": "Address where the webhook will be sent when initial media analysis finishes"
    },
    "user_data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        }
      },
      "description": "Custom user data that will be stored along with the Mediafile and returned when reading the Mediafile. An option to add some context."
    },
    "source_id": {
      "type": "string",
      "description": "ID of Mediafile to use as a source"
    },
    "action": {
      "type": "string",
      "description": "name of the action to perform"
    },
    "options": {
      "type": "object",
      "properties": {
        "preset": {
          "type": "string",
          "description": "selected remaster preset name"
        },
        "duration": {
          "type": "number",
          "description": "limit length to number of seconds"
        },
        "offset": {
          "type": "number",
          "description": "skip first number seconds"
        },
        "html5_compatible": {
          "type": "boolean",
          "description": "use HTML5 compatible codec"
        }
      },
      "required": [
        "preset"
      ],
      "description": "action specific options"
    }
  },
  "required": [
    "source_id",
    "action"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "mediafile": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "remaster",
    "status": "pending",
    "options": {
      "preset": "max_presence",
      "duration": "90",
      "offset": "10",
      "html5_compatible": "false"
    },
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string"
            }
          }
        },
        "action": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "options": {
          "type": "object",
          "properties": {
            "preset": {
              "type": "string"
            },
            "duration": {
              "type": "string"
            },
            "offset": {
              "type": "string"
            },
            "html5_compatible": {
              "type": "string"
            }
          }
        },
        "webhook_url": {
          "type": "string"
        },
        "user_data": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "created_at",
        "updated_at",
        "expires_at",
        "url",
        "metadata",
        "action",
        "status",
        "options",
        "webhook_url",
        "user_data"
      ],
      "additionalProperties": false
    }
  }
}
Response  400
HideShow

Request body is malformed.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "bad_request",
    "message": "Required param is missing or the value is empty: action."
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  422
HideShow

Can not process Mediafile. The reasons may vary - not supported action, unknown profile etc.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unprocessable_entity",
    "message": "Remastering preset not found: low_bass."
  }
}

Create Waveform
POST/mediafiles/process

Creates waveform. Waveform Mediafile is final. It cannot be used as a source for a new Mediafile as it is an image.

Waveform action has no options.

Example URI

POST https://api.remastermedia.com/v2/mediafiles/process
Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Body
{
  "webhook_url": "https://name.example.com/hook",
  "user_data": {
    "order_id": "1234"
  },
  "source_id": "56323",
  "action": "waveform"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "webhook_url": {
      "type": "string",
      "description": "Address where the webhook will be sent when initial media analysis finishes"
    },
    "user_data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        }
      },
      "description": "Custom user data that will be stored along with the Mediafile and returned when reading the Mediafile. An option to add some context."
    },
    "source_id": {
      "type": "string",
      "description": "ID of Mediafile to use as a source"
    },
    "action": {
      "type": "string",
      "description": "name of the action to perform"
    },
    "options": {
      "type": "object",
      "properties": {},
      "description": "action specific options"
    }
  },
  "required": [
    "source_id",
    "action"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "mediafile": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "waveform",
    "status": "pending",
    "options": {},
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string"
            }
          }
        },
        "action": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "options": {
          "type": "object",
          "properties": {}
        },
        "webhook_url": {
          "type": "string"
        },
        "user_data": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "created_at",
        "updated_at",
        "expires_at",
        "url",
        "metadata",
        "action",
        "status",
        "options",
        "webhook_url",
        "user_data"
      ],
      "additionalProperties": false
    }
  }
}
Response  400
HideShow

Request body is malformed.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "bad_request",
    "message": "Required param is missing or the value is empty: action."
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  422
HideShow

Can not process Mediafile. The reasons may vary - not supported action, wrong Mediafile etc.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unprocessable_entity",
    "message": "Remastering preset not found: low_bass."
  }
}

Create Poster
POST/mediafiles/process

Creates poster. Poster Mediafile is final. It cannot be used as a source for a new Mediafile as it is an image.

Poster action has no options.

Example URI

POST https://api.remastermedia.com/v2/mediafiles/process
Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Body
{
  "webhook_url": "https://name.example.com/hook",
  "user_data": {
    "order_id": "1234"
  },
  "source_id": "56323",
  "action": "poster"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "webhook_url": {
      "type": "string",
      "description": "Address where the webhook will be sent when initial media analysis finishes"
    },
    "user_data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        }
      },
      "description": "Custom user data that will be stored along with the Mediafile and returned when reading the Mediafile. An option to add some context."
    },
    "source_id": {
      "type": "string",
      "description": "ID of Mediafile to use as a source"
    },
    "action": {
      "type": "string",
      "description": "name of the action to perform"
    },
    "options": {
      "type": "object",
      "properties": {},
      "description": "action specific options"
    }
  },
  "required": [
    "source_id",
    "action"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "mediafile": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "poster",
    "status": "pending",
    "options": {},
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string"
            }
          }
        },
        "action": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "options": {
          "type": "object",
          "properties": {}
        },
        "webhook_url": {
          "type": "string"
        },
        "user_data": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "created_at",
        "updated_at",
        "expires_at",
        "url",
        "metadata",
        "action",
        "status",
        "options",
        "webhook_url",
        "user_data"
      ],
      "additionalProperties": false
    }
  }
}
Response  400
HideShow

Request body is malformed.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "bad_request",
    "message": "Required param is missing or the value is empty: action."
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  422
HideShow

Can not process Mediafile. The reasons may vary - not supported action, unknown profile etc.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unprocessable_entity",
    "message": "Remastering preset not found: low_bass."
  }
}

Denoise
POST/mediafiles/process

Performs noise reduction on a Mediafile. To perform noise reduction you can either use a predefined noise reduction preset (see List noise reduction presets) or you can directly supply the noice reduction parameter through dedicated options. If both are provided the preset will be loaded first and then options explicitely listed in the request will override the values from the preset.

There is an option to use HTML5 compatible format for the output media which will convert the output media audio to 320kbps MP3 and video to 800kbps H264 MP4 with resolution scaled down to 640x480 pixels.

Options:

  • preset - Preset name. (string, required)

  • offset - Skip first number seconds fro Mediafile. If not set the processing will start from the beginning of the Mediafile. (number, optional)

  • duration - Limit length of the output in seconds. If not set the processing will take everything till the end of the Mediafile (number, optional)

  • html5_compatible - Create output in HTML5 compatible codec/format (boolean, optional)

  • algorithm - Set the algorithm to use when performing noise reduction. Available values are: 0 = AI Clarity v1 algorithm, 1 = AI Natural v1 algorithm. See more in Noise reduction chapter. (number, optional)

  • aggressiveness - Set the aggressiveness of the noise reduction algorithm. 0 = Not aggressive 1 = Normal aggressive 2 = Very aggressive. See more in Noise reduction chapter. (number, optional)

  • amount - Control the amount of AI Noise Reduction as a percentage. Values are float numbers between 0 and 1. See more in Noise reduction chapter. (number, optional)

  • gain - Set the noise reduction gain. See more in Noise reduction chapter. (number, optional)

  • lower_bound - Set the lower bound of the noise reduction algorithm. Values are numbers between 0 and 1, where 0 = reduction only 1 = noisy only. See more in Noise reduction chapter. (number, optional)

Example URI

POST https://api.remastermedia.com/v2/mediafiles/process
Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Body
{
  "webhook_url": "https://name.example.com/hook",
  "user_data": {
    "order_id": "1234"
  },
  "source_id": "56323",
  "action": "denoise",
  "options": {
    "preset": "low_noise_reduction",
    "duration": 90,
    "aggressiveness": "2",
    "amount": "0.65"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "webhook_url": {
      "type": "string",
      "description": "Address where the webhook will be sent when initial media analysis finishes"
    },
    "user_data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        }
      },
      "description": "Custom user data that will be stored along with the Mediafile and returned when reading the Mediafile. An option to add some context."
    },
    "source_id": {
      "type": "string",
      "description": "ID of Mediafile to use as a source"
    },
    "action": {
      "type": "string",
      "description": "name of the action to perform"
    },
    "options": {
      "type": "object",
      "properties": {
        "preset": {
          "type": "string",
          "description": "selected remaster preset name"
        },
        "duration": {
          "type": "number",
          "description": "limit length to number of seconds"
        },
        "aggressiveness": {
          "type": "string"
        },
        "amount": {
          "type": "string"
        }
      },
      "required": [
        "preset"
      ],
      "description": "action specific options"
    }
  },
  "required": [
    "source_id",
    "action"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "mediafile": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "denoise",
    "status": "pending",
    "options": {
      "preset": "low_noise_reduction",
      "duration": 90,
      "aggressiveness": "2",
      "amount": "0.65"
    },
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string"
            }
          }
        },
        "action": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "options": {
          "type": "object",
          "properties": {
            "preset": {
              "type": "string",
              "description": "selected remaster preset name"
            },
            "duration": {
              "type": "number",
              "description": "limit length to number of seconds"
            },
            "aggressiveness": {
              "type": "string"
            },
            "amount": {
              "type": "string"
            }
          },
          "required": [
            "preset"
          ]
        },
        "webhook_url": {
          "type": "string"
        },
        "user_data": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "created_at",
        "updated_at",
        "expires_at",
        "url",
        "metadata",
        "action",
        "status",
        "options",
        "webhook_url",
        "user_data"
      ],
      "additionalProperties": false
    }
  }
}
Response  400
HideShow

Request body is malformed.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "bad_request",
    "message": "Required param is missing or the value is empty: action."
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  422
HideShow

Can not process Mediafile. The reasons may vary - not supported action, unknown profile etc.

Headers
Content-Type: application/json
Body
{
    "error": {
        "code": "unprocessable_entity",
        "message": "Remastering preset not found: mild_noise_reduction."
    }

Mediafile Details

Gets the details of a particular Mediafile.

Mediafile Details
GET/mediafiles/{id}

Example URI

GET https://api.remastermedia.com/v2/mediafiles/id
URI Parameters
HideShow
id
string (required) 

ID of the Mediafile.

Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "mediafile": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3`",
      "container": "mp3",
      "audio_stream": {
        "bit_rate": "320k",
        "channels": 2,
        "codec_name": "libmp3lame",
        "sample_rate": "44100"
      }
    },
    "action": "analysis",
    "status": "success",
    "options": {},
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string"
            },
            "container": {
              "type": "string"
            },
            "audio_stream": {
              "type": "object",
              "properties": {
                "bit_rate": {
                  "type": "string"
                },
                "channels": {
                  "type": "number"
                },
                "codec_name": {
                  "type": "string"
                },
                "sample_rate": {
                  "type": "string"
                }
              }
            }
          }
        },
        "action": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "success",
            "failed",
            "success"
          ]
        },
        "options": {
          "type": "object",
          "properties": {}
        },
        "webhook_url": {
          "type": "string"
        },
        "user_data": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "created_at",
        "updated_at",
        "expires_at",
        "url",
        "metadata",
        "action",
        "status",
        "options",
        "webhook_url",
        "user_data"
      ],
      "additionalProperties": false
    }
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  404
HideShow

Mediafile nas no been found.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "not_found",
    "message": "Mediafile has not been found."
  }
}

Source Mediafile

Source Mediafile is a Mediafile used as an input for the requested Mediafile. This way you can track previous media version and go back to try different audio action.

Source of the Mediafile you provide as a first (with no action applied to it yet) is always null.

Source Mediafile
GET/mediafile/{id}/source

Example URI

GET https://api.remastermedia.com/v2/mediafile/id/source
URI Parameters
HideShow
id
string (required) 

ID of the Mediafile.

Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "mediafile": {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3`",
      "container": "mp3",
      "audio_stream": {
        "bit_rate": "320k",
        "channels": 2,
        "codec_name": "libmp3lame",
        "sample_rate": "44100"
      }
    },
    "action": "analysis",
    "status": "success",
    "options": {},
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string"
            },
            "container": {
              "type": "string"
            },
            "audio_stream": {
              "type": "object",
              "properties": {
                "bit_rate": {
                  "type": "string"
                },
                "channels": {
                  "type": "number"
                },
                "codec_name": {
                  "type": "string"
                },
                "sample_rate": {
                  "type": "string"
                }
              }
            }
          }
        },
        "action": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "success",
            "failed",
            "success"
          ]
        },
        "options": {
          "type": "object",
          "properties": {}
        },
        "webhook_url": {
          "type": "string"
        },
        "user_data": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "created_at",
        "updated_at",
        "expires_at",
        "url",
        "metadata",
        "action",
        "status",
        "options",
        "webhook_url",
        "user_data"
      ],
      "additionalProperties": false
    }
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  404
HideShow

Mediafile nas no been found.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "not_found",
    "message": "Mediafile has not been found."
  }
}

Derived Mediafiles

Derived Mediafiles are created when you apply audio action on other Mediafile. After you apply some audio action, the new Mediafile is a derived Mediafile of the original Mediafile. You can think of derived Mediafiles as children and source Mediafile as a parent in a tree.

Derived Mediafiles
GET/mediafile/{id}/derived

Example URI

GET https://api.remastermedia.com/v2/mediafile/id/derived
URI Parameters
HideShow
id
string (required) 

ID of the Mediafile.

Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "mediafiles": [
    {
      "id": "42974",
      "created_at": "2020-01-08T02:15:15Z",
      "updated_at": "2020-01-08T02:15:15Z",
      "expires_at": "2020-02-08T02:15:15Z",
      "url": "https://name.example.com/path/song.mp3",
      "metadata": {
        "filename": "song.mp3"
      },
      "action": "",
      "status": "success",
      "options": {},
      "webhook_url": "https://example.com/hook",
      "user_data": {}
    },
    {
      "id": "42974",
      "created_at": "2020-01-08T02:15:15Z",
      "updated_at": "2020-01-08T02:15:15Z",
      "expires_at": "2020-02-08T02:15:15Z",
      "url": "https://name.example.com/path/song.mp3",
      "metadata": {
        "filename": "song.mp3`",
        "container": "mp3",
        "audio_stream": {
          "bit_rate": "320k",
          "channels": 2,
          "codec_name": "libmp3lame",
          "sample_rate": "44100"
        }
      },
      "action": "analysis",
      "status": "success",
      "options": {},
      "webhook_url": "https://example.com/hook",
      "user_data": {}
    },
    {
      "id": "42974",
      "created_at": "2020-01-08T02:15:15Z",
      "updated_at": "2020-01-08T02:15:15Z",
      "expires_at": "2020-02-08T02:15:15Z",
      "url": "https://name.example.com/path/song.mp3",
      "metadata": {
        "filename": "song.mp3"
      },
      "action": "remaster",
      "status": "success",
      "options": {
        "preset": "max_presenece"
      },
      "webhook_url": "https://example.com/hook",
      "user_data": {}
    },
    {
      "id": "42974",
      "created_at": "2020-01-08T02:15:15Z",
      "updated_at": "2020-01-08T02:15:15Z",
      "expires_at": "2020-02-08T02:15:15Z",
      "url": "https://name.example.com/path/song.mp3",
      "metadata": {
        "filename": "song.mp3"
      },
      "action": "remaster",
      "status": "success",
      "options": {
        "preset": "level_boost",
        "offset": "12"
      },
      "webhook_url": "https://example.com/hook",
      "user_data": {}
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mediafiles": {
      "type": "array"
    }
  }
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  404
HideShow

Mediafile nas no been found.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "not_found",
    "message": "Mediafile has not been found."
  }
}

Mediafiles Collection

Collection of Mediafiles objects. Retrieves Mediafiles that were created between from and to time. Lists 100 results per response. Use page parameter to iterate over older results.

List Mediafiles
GET/mediafiles?from={from}&to={to}&page={page}

Example URI

GET https://api.remastermedia.com/v2/mediafiles?from=from&to=to&page=page
URI Parameters
HideShow
from
string (required) 

Beginning of time range as RFC3339

to
string (required) 

End of time range as RFC3339

page
number (optional) 

default 1

Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "",
    "status": "success",
    "options": {},
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  },
  {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3`",
      "container": "mp3",
      "audio_stream": {
        "bit_rate": "320k",
        "channels": 2,
        "codec_name": "libmp3lame",
        "sample_rate": "44100"
      }
    },
    "action": "analysis",
    "status": "success",
    "options": {},
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  },
  {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "remaster",
    "status": "success",
    "options": {
      "preset": "max_presenece"
    },
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  },
  {
    "id": "42974",
    "created_at": "2020-01-08T02:15:15Z",
    "updated_at": "2020-01-08T02:15:15Z",
    "expires_at": "2020-02-08T02:15:15Z",
    "url": "https://name.example.com/path/song.mp3",
    "metadata": {
      "filename": "song.mp3"
    },
    "action": "remaster",
    "status": "success",
    "options": {
      "preset": "level_boost",
      "offset": "12"
    },
    "webhook_url": "https://example.com/hook",
    "user_data": {}
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}
Response  422
HideShow

Can not process the request, because parameters are either mising or malformed.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unprocessable_entity",
    "message": "Mediafile has not been found."
  }
}

Action details

Actions are processes that can be applied to mediafiles. You can get information that is necessary for performing those actions.

Presets lists

Presets are predefined settings sets for processes that can be applied to mediafiles. You will use (for remastering) or may use (for noise reduction) these presets. To be able to do that you need to get available presets.

List Remastering Presets

List Remastering Presets
GET/actions/remaster/presets

Collection of all available remastering presets organized in categories.

To see how to apply remastering preset on Mediafile see Create new Mediafile

Example URI

GET https://api.remastermedia.com/v2/actions/remaster/presets
Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Response  200
HideShow

The presets are organized categories (such as Web/Mobile or Broadcast).

Headers
Content-Type: application/json
Body
{
  "categories": [
    {
      "title": "Web/Mobile",
      "presets": [
        {
          "title": "Max Presence",
          "name": "maxpresence",
          "description": "Superior EQ enhancement for music",
          "definition_file": "https://s3_bucket.s3-accelerate.amazonaws.com/presets/maxpresence.bgps",
          "updated_at": "2019-12-05T10:11:08.094Z"
        },
        {
          "title": "Balanced Clarity",
          "name": "balancedclarity",
          "description": "Balanced EQ level enhancement for music and voice over",
          "definition_file": "https://s3_bucket.s3-accelerate.amazonaws.com/presets/balancedclarity.bgps",
          "updated_at": "2019-12-05T10:11:08.094Z"
        }
      ]
    },
    {
      "title": "Special Applications",
      "presets": [
        {
          "title": "Voice Focus",
          "name": "voicefocus",
          "description": "Use for heavy background noise where recorded voice needs to be enhanced",
          "definition_file": "https://s3_bucket.s3-accelerate.amazonaws.com/presets/voicefocus.bgps",
          "updated_at": "2019-12-05T10:11:10.321Z"
        }
      ]
    }
  ]
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}

List noise reduction presets

List noise reduction presets
GET/actions/denoise/presets

Collection of all available noise reduction presets organized in categories.

To see how to apply noise reduction preset on Mediafile see Create new Mediafile

Example URI

GET https://api.remastermedia.com/v2/actions/denoise/presets
Request
HideShow
Headers
Content-Type: application/json
Authorization: <Auth Token>
Response  200
HideShow

The presets are organized categories (such as Base or With noise gate).

Headers
Content-Type: application/json
Body
{
  "categories": [
    {
      "title": "Base",
      "presets": [
        {
          "title": "Low Noise Reduction",
          "name": "low_noise_reduction",
          "description": "Low noise reduction suitable for any kind of content",
          "definition_file": "https://s3_bucket.s3-accelerate.amazonaws.com/presets/low_noise_reduction.bgps",
          "updated_at": "2019-12-05T10:11:08.094Z"
        },
        {
          "title": "Medium Noise Reduction",
          "name": "medium_noise_reduction",
          "description": "Medium noise reduction suitable for any kind of content",
          "definition_file": "https://s3_bucket.s3-accelerate.amazonaws.com/presets/medium_noise_reduction.bgps",
          "updated_at": "2019-12-05T10:11:08.094Z"
        }
      ]
    },
    {
      "title": "With noise gate",
      "presets": [
        {
          "title": "Low Noise Reduction with noise gate",
          "name": "low_noise_reduction_ng",
          "description": "Low noise reduction with noise gate (threshold 0 dB, sensitivity 10 dB)",
          "definition_file": "https://s3_bucket.s3-accelerate.amazonaws.com/presets/low_noise_reduction_ng.bgps",
          "updated_at": "2019-12-05T10:11:10.321Z"
        }
      ]
    }
  ]
}
Response  401
HideShow

The request is not authorized either by missing or invalid authentication token.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid authentication token."
  }
}

Webhooks

Overview

When you apply an action on Mediafile, you have an option to provide webhook_url attribute and receive webhook event when Mediafile processing finishes.

Webhook event is a POST HTTP request to the url you provide with body in a following format:

{
            "created_at": "2020-01-08T02:15:15Z"
            "event": "action.success",
            "payload": {
              "mediafile": {
                "id": "42974",
                ...
              }
            }
        }

where event is a is an event name and payload contains updated Mediafile.

Webhook Events

  • analysis.success

  • analysis.failed

  • action.success

  • action.failed

Errors

Overview

There are a number of error responses you might receive if your request is in some way invalid.

General format of an error response is following:

{
    "code": "unauthorized",
    "message": Invalid credentials
  }

where code is an HTTP response name and message is a human friendly description of the error.

Noise reduction

Algorithm

Following noise reduction algorithms are available.

Name Description Identifier
AI Clarity v1 This algorithm will attempt to create a completely dry (no reverberation or background noise) speech result. Works will with radio or telephone voices and other headset use cases. 0
AI Natural v1 This algorithm will detect speech then attempt to remove non-speech signals while keeping the voice a natural-sounding as possible. Allows adjustment of Aggressiveness and Lower Bound for fine-tuning. 1

Amount

Adjusts the amount of AI Noise Reduction as a percentage (float 0 to 1). This automatically adjusts NrGain and InputGain for an easy-to-use user-facing feature.

Range Percentage Float
Minimum 0% 0.0
Median 50% 0.5
Maximum 100% 1.0

Aggressiveness

This is available when the AI Natural v1 (algorithm ID 1) noise reduction algorithm is selected.

Description Value
Not aggressive - Will attempt to have minimal impact on the voice when removing noise 0
Normal – Will allow small impact on the voice to remove noise 1
Very Aggressive – Will allow more impact on the voice to remove as much noise as possible 2

Gain

Sets the level of the noise reduction algorithm output.

Range Decibels Float
Minimum -40dB 0.01
Unity 0dB 1.0
Maximum +6dB 2.0

LowerBound

This is available when the AI Natural v1 (algorithm ID 1) noise reduction algorithm is selected. This parameter is used to limit the amount of noise reduction to provide a more natural-sounding result. The “lower bound” represents the maximum allowed noise reduction by the algorithm.

NOTE: This API is set as a range between 0 (maximum noise reduction) and 1 (no noise reduction). However, we recommend using a decibel conversion to provide easier control for the user.

Range Description Value
Maximum (100%) noise reduction (about -40dB) 0
Medium (50%) noise reduction (about -6dB) 0.5
None (0%) same as source 1

Generated by aglio on 22 Oct 2021