Getting a Transcription


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 an audio file and request a transcript 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 Audio

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 audio files as shown:

  • curl
curl --data "media_url=http://media.clarify.io/audio/books/dorothyandthewizardinoz_01_baum_64kb.mp3" \
     --data "notify_url=http://example.org/sample-receiver" \
     --data "name=Dorothy and the Wizard of Oz" 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 audio and 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 a Transcript

The most important part 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 transcript.

  • curl
curl --data "insight=transcript_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": "56789abcde",
    "bundle_id": "abcde12345",
    "name": "transcript",
    "status": "processing"
    "created": "2015-04-12T03:14:53.253Z",
    "updated": "2015-04-16T21:05:03.896Z",
    "track_data": [
        {
        }
    ],
    "_class": "TranscriptR9Insight",
    "_links": {
        "self": {
            "href": "/v1/bundles/abcde12345/insights/56789abcde"
        },
        "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 Transcript

This is where the notify_url becomes important again. Just as we perform a callback once the indexing is complete, we also make a request once the transcript is ready. Here are the contents of that payload:
{
    "bundle_id": "abcde12345",
    "name": "Dorothy and the Wizard of Oz",
    "external_id": "external_123",
    "insight": "transcript_r9",
    "insight_id": "56789abcde",
    "updated": "2015-04-30T01:11:19.889Z",
    "_class": "InsightNotification",
    "_links": {
        "curies": [
            {
                "href": "/docs/rels/{rel}",
                "name": "clarify",
                "templated": true
            },
            {
                "href": "/docs/insights/{rel}",
                "name": "insight",
                "templated": true
            }
        ],
        "clarify:insights": {
            "href": "/v1/bundles/abcde12345/insights"
        },
        "clarify:bundle": {
            "href": "/v1/bundles/abcde12345"
        },
        "clarify:tracks": {
            "href": "/v1/bundles/abcde12345/tracks"
        },
        "insight:transcript_r9": {
            "href": "/v1/bundles/abcde12345/insights/56789abcde"
        }
    }
}
The most important part of this payload is the href of the insight:transcript_r9 key. By retrieving the contents of that URI, Clarify will give you a complete list of the words recognized from the audio.
  • curl
curl https://api.clarify.io/v1/bundles/abcde12345/insights/56789abcde \
     --header "Authorization: Bearer myapikey"  | jq '.'
# The jq portion is optional and just used to pretty print the resulting json
The result of which will be a JSON representation of the transcript as shown below. Based on the number and duration of the audio, there will be anywhere from zero to many 'segments,' each describing one portion of the dialog. As long as speech is found, there will be at least one 'speaker' but they may be many depending on how detection works.
{
    "id": "56789abcde",
    "bundle_id": "abcde12345",
    "name": "transcript_r9",
    "status": "ready",
    "created": "2015-05-14T21:50:17.245Z",
    "updated": "2015-05-14T21:57:30.139Z",
    "data": {
        "transcript": {
            "meta": {
                "format": "clarify_transcript",
                "version": 1
            },
            "segments": [
                {
                    "speaker": "Speaker 1",
                    "terms": [
                        {
                            "term": "Thank"
                        },
                        {
                            "term": "you"
                        },
                        {
                            "term": "for"
                        },
                        {
                            "term": "calling"
                        },
                        {
                            "term": "clarify"
                        },
                        {
                            "term": ".",
                            "type": "mark"
                        }
                    ]
                },
                {
                    "speaker": "Speaker 2",
                    "terms": [
                        {
                            "term": "How"
                        },
                        {
                            "term": "are"
                        },
                        {
                            "term": "you"
                        },
                        {
                            "term": "?",
                            "type": "mark"
                        }
                    ]
                },
                {
                    "speaker": "Speaker 1",
                    "terms": [
                        {
                            "term": "Good"
                        },
                        {
                            "term": ".",
                            "type": "mark"
                        },
                        {
                            "term": "I'm"
                        },
                        {
                            "term": "well"
                        },
                        {
                            "term": ",",
                            "type": "mark"
                        },
                        {
                            "term": "thank"
                        },
                        {
                            "term": "you"
                        },
                        {
                            "term": ".",
                            "type": "mark"
                        }
                    ]
                }
            ],
            "speakers": [
                {
                    "id": "Speaker 1",
                    "label": "Agent"
                },
                {
                    "id": "Speaker 2",
                    "label": "Customer"
                }
            ]
        }
    },
    "_class": "TranscriptR9Insight",
    "_links": {
        "self": {
            "href": "/v1/bundles/abcde12345/insights/56789abcde"
        },
        "curies": [
        {
            "href": "/docs/rels/{rel}",
            "name": "clarify",
            "templated": true
        }
        ],
        "parent": {
            "href": "/v1/bundles/abcd1234/insights"
        },
        "clarify:bundle": {
            "href": "/v1/bundles/abcd1234"
        }
    }
}
Fork me on GitHub