Getting Closed Captions


Note: Since these are generated by humans, it will take a minimum of 72 hours to receive the callback. If you need results faster, please contact Support.
This quickstart demonstrates how to load a video file and request clsoed captions in just a matter of minutes.

Configuring Your Environment

While you can use any programming language you choose, we provide a few helper libraries to get you started. In most cases, you can use your favorite package manager:

  • curl
Although we don't have a curl library, the command-line JSON parser 'jq' is super helpful. Download and install it to get started: http://stedolan.github.io/jq/

Loading Video

First include the SDK and create your object using your API Key. Once you’ve created the object, you can use the object to load each of your video files as shown:

  • curl
curl --data "media_url=http://media.clarify.io/video/presentations/SirKenRobinson-TED2006-How-Schools-Kill-Creativity.mp4" \
     --data "notify_url=http://example.org/sample-receiver" \
     --data "name=Sir Ken Robinson – TED 2006" https://api.clarify.io/v1/bundles \
     --X POST --header "Authorization: Bearer myapikey" | jq '.'
# The jq portion is optional and just used to pretty print the resulting json

Naming the bundle and providing a notify_url are both optional. We have a number of video files available for processing on our Media Page.

Note: You don't have to download these files. Instead you can pass the urls via the create/POST method shown above.
After creating a bundle, you'll receive a response which looks something like this:
{
    "id":"abcde12345",
    "_class":"Ref",
    "_links":{
        "self":{
            "href":"/v1/bundles/abcde12345"
        },
        "curies":[
            {
                "href":"/docs/rels/{rel}",
                "name":"clarify",
                "templated":true
            }
        ],
        "clarify:metadata":{
            "href":"/v1/bundles/abcde12345/metadata"
        },
        "clarify:tracks":{
            "href":"/v1/bundles/abcde12345/tracks"
        },
        "clarify:insights":{
            "href":"/v1/bundles/abcde12345/insights"
        }
    }
}

Ordering Captions

The most important part of the response is the href of the clarify:insights key. By making an HTTP POST to that URI, Clarify will start processing the audio to create the captions.

  • curl
curl --data "insight=captions_r9" https://api.clarify.io/v1/bundles/abcde12345/insights \
     --header "Authorization: Bearer myapikey" | jq '.'
# The jq portion is optional and just used to pretty print the resulting json

This will return JSON with the status of the request:

{
    "id": "fadbe12345",
    "bundle_id": "abcde12345",
    "name": "captions_r9",
    "status": "processing",
    "created": "2015-12-25T03:53:34.819Z",
    "updated": "2015-12-25T03:53:34.819Z",
    "track_data": [
        {}
    ],
    "_class": "CaptionsR9Insight",
    "_links": {
        "self": {
            "href": "/v1/bundles/abcde12345/insights/fadbe23456"
        },
        "curies": [
            {
                "href": "/docs/rels/{rel}",
                "name": "clarify",
                "templated": true
            }
        ],
        "parent": {
            "href": "/v1/bundles/abcde12345/insights"
        },
        "clarify:bundle": {
            "href": "/v1/bundles/abcde12345"
        }
    }
}
Note: Since these are generated by humans, it will take a minimum of 72 hours to receive the callback. If you need results faster, please contact Support.

Getting your Captions

To retrieve your completed captions, you have two options. First, you can store the href of the self key from your previous request to retrieve the captions list directly. That's the easiest and fastest way. Alternatively, you can use the href of the clarify:insights key. By retrieving the contents of that URI, Clarify will give you a list of the Insights available.
  • curl
curl https://api.clarify.io/v1/bundles/abcde12345/insights \
     --header "Authorization: Bearer myapikey"  | jq '.'
# The jq portion is optional and just used to pretty print the resulting json
This gives you a master list of all insights currently available to you. It's worth noting that this list will change over time as we add new insights to the system.
{
    "bundle_id": "abcde12345",
    "created": "2015-03-04T05:03:04.292Z",
    "updated": "2015-05-16T20:39:37.508Z",
    "_class": "Insights",
    "_links": {
        "curies": [
            {
                "href": "/docs/insights/{rel}",
                "name": "insight",
                "templated": true
            }
        ],
        "insight:captions_r9": {
            "href": "/v1/bundles/abcde12345/insights/fadbe23456"
        }
        "parent": {
            "href": "/v1/bundles/abcde12345"
        },
        "self": {
            "href": "/v1/bundles/abcde12345/insights"
        }
    }
}
In this list, the href of the insight:captions_r9 is the important part and the same as the self link noted above. By retrieving the contents of that URI, Clarify will give you a complete list of the available file formats for your captions.
  • curl
curl https://api.clarify.io/v1/bundles/abcde12345/insights/fadbe23456 \
    --header "Authorization: Bearer myapikey"  | jq '.'
# The jq portion is optional and just used to pretty print the resulting json
The resulting payload includes individual links to all of the available closed captioning formats. Here's the full response:
{
    "id": "fadbe23456",
    "bundle_id": "abcde12345",
    "name": "captions_r9",
    "status": "ready",
    "created": "2015-12-20T15:47:20.459Z",
    "updated": "2015-12-20T16:00:56.298Z",
    "track_data": [
        {}
    ],
    "_class": "CaptionsR9Insight",
    "_links": {
        "self": {
            "href": "/v1/bundles/abcde12345/insights/fadbe23456"
        },
        "curies": [
            {
                "href": "/docs/rels/{rel}",
                "name": "clarify",
                "templated": true
            },
            {
                "href": "/docs/insights/captions/{rel}",
                "name": "captions",
                "templated": true
            }
        ],
        "parent": {
            "href": "/v1/bundles/abcde12345/insights"
        },
        "clarify:bundle": {
            "href": "/v1/bundles/abcde12345"
        },
        "captions:vtt": [
            {
                "href": "/v1/bundles/abcde12345/insights/fadbe23456/_links?rel=captions%3Avtt&track_id=badee12345",
                "name": "badee12345"
            }
        ],
        "captions:ttml": [
            {
                "href": "/v1/bundles/abcde12345/insights/fadbe23456/_links?rel=captions%3Attml&track_id=badee12345",
                "name": "badee12345"
            }
        ],
        "captions:srt": [
            {
                "href": "/v1/bundles/abcde12345/insights/fadbe23456/_links?rel=captions%3Asrt&track_id=badee12345",
                "name": "badee12345"
            }
        ],
        "captions:scc": [
            {
                "href": "/v1/bundles/abcde12345/insights/fadbe23456/_links?rel=captions%3Ascc&track_id=badee12345",
                "name": "badee12345"
            }
        ]
    }
}
You can now retrieve any of the closed captioning formats you need. In this request, we'll retrieve the SRT or SubRip format:
  • curl
curl https://api.clarify.io/v1/bundles/abcde12345/insights/fadbe23456/_links?rel=captions%3Asrt&track_id=badee12345 \
    --header "Authorization: Bearer myapikey"  | jq '.'
# The jq portion is optional and just used to pretty print the resulting json
From here, you can load the resulting file into your video player or your favorite media management platform such as Brightcove or Vimeo. At this point, it's up to you.
Fork me on GitHub