Media Service API

The Media Service APIs allows clients to burn subtitles on to a video with some styling. The input video is defined by an S3 bucket name and key along with the video dimensions. The subtitles can be defined by an SRT file.

Endpoints

All API requests require the x-api-key header to be set with the API key received at registration.

API paths use base URL https://api.getsubly.com

Burn Media

For the Burn Media service, clients provide an input media item and subtitles to the Subly Media API. Subly then burns the subtitles to a video and writes the output to the requested location.

Burn Media Request

Endpoint: POST /media/burn

Body Format: Content-Type: application/json

Body

• input
  • video
    • bucket (string): Bucket containing the video file
    • key (string): Key to identify the video file in the bucket
    • width (number): width of video
    • height (number): height of video
  • subtitles
    • bucket (string): Bucket containing the subtitle file
    • key (string): Key to identify the subtitle file in the bucket
    • format (string): SRT, ASS, JSON
    • config (object): Style options for subtitles (for full details see Media Configuration)
• output
  • bucket (string): Bucket to put output video file
  • key (string): location of output video file

The possible formats for the input subtitles are:

• SRT: SubRip Subtitle format
• ASS: Advanced SubStation Alpha
• JSON: Subly Transcription Format. If using the Subly iframe this is the format of the transcription response (for full details see Subly Transcription)

Example

{
  "input": {
    "video": {
      "bucket": "my-storage-bucket",
      "key": "my-video.mp4",
      "width": 1080,
      "height": 1920
    },
    "subtitles": {
      "bucket": "my-storage-bucket",
      "key": "my-subtitles.srt",
      "format": "SRT",
      "config": {
        "font": "Courier New",
        "fontSize": 40,
        "colorBack": "000000",
        "colorOutline": "000000",
        "colorPrimary": "FFFFFF",
        "colorSecondary": "0000FF",
        "bold": 0,
        "italic": -1,
        "strikeOut": 0,
        "underline": 0,
        "scaleX": 100,
        "scaleY": 100,
        "spacing": 0,
        "angle": 0,
        "alignment": 2,
        "backgroundStyle": "Background",
        "borderStyle": 3,
        "encoding": 0,
        "hasBackground": true,
        "marginL": 100,
        "marginR": 100,
        "marginV": 100,
        "outline": 10,
        "playResX": 1920,
        "playResY": 1080,
        "shadow": 0.5
      }
    }
  },
  "output": {
    "bucket": "my-storage-bucket",
    "key": "my-video-with-subtitles.mp4"
  }
}

Response

200 status for successful job

• jobId (string): ID of the burn job

Example Response

{
  "jobId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf"
}

Burn Job Status

Endpoint: GET /media/burn/status/:jobId

Body Format: Content-Type: application/json

Parameters

• jobId (string): Job to get status for

Response

200 status for valid job ID

• jobId (string)
• status (string) - PENDING, COMPLETE, FAILED
• started (timestamp)
• completed (timestamp - optional)
• progress
  • overallProgress (number) - Percentage complete (0 - 100)
• errors (array of string) - any errors if the job is FAILED

Example Response

{
  "jobId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf",
  "status": "PENDING",
  "started": "2021-05-31T11:57:32.992Z",
  "progress": {
    "overallProgress": 88
  }
}

Convert Transcription

Convert a transcription into another transcription format e.g. convert SRT to VTT

Endpoint: POST /media/file/convert

Body Format: Content-Type: application/json

Body

• input
  • bucket (string): Bucket containing the video file
  • key (string): Key to identify the video file in the bucket
  • format (string): SRT
  • config (object - optional): Style options for subtitles (for full details see Media Configuration)
• output
  • format (string): SRT, VTT, TXT

Example

{
  "input": {
    "bucket": "my-storage-bucket",
    "key": "my-transcript.srt",
    "format": "SRT",
    "config": {
      "font": "Courier New",
      "fontSize": 40,
      "colorBack": "000000",
      "colorOutline": "000000",
      "colorPrimary": "FFFFFF",
      "colorSecondary": "0000FF",
      "bold": 0,
      "italic": -1,
      "strikeOut": 0,
      "underline": 0,
      "scaleX": 100,
      "scaleY": 100,
      "spacing": 0,
      "angle": 0,
      "alignment": 2,
      "backgroundStyle": "Background",
      "borderStyle": 3,
      "encoding": 0,
      "hasBackground": true,
      "marginL": 100,
      "marginR": 100,
      "marginV": 100,
      "outline": 10,
      "playResX": 640,
      "playResY": 640,
      "shadow": 0.5
    }
  },
  "output": {
    "format": "VTT"
  }
}

Response

200 status for a successful request

• format (string): SRT, VTT, TXT
• text (string): The converted output

Example Response

{
  "format": "VTT",
  "text": "WEBVTT\n\nNOTE\nTo enable cue styles, please remove above 'NOTE' line as well as this line.\nSTYLE\n::cue {\n\tfont-family: Courier New;\n\tfont-style: italic;\n\tcolor: #FFFFFF;\n\tbackground-color: #000000FF;\n}\n\n1\n00:00:03.440 --> 00:00:06.770 line:14 align:middle\nline one.\n\n2\n00:00:07.240 --> 00:00:10.270 line:14 align:middle\nline two.\n"
}