Transcribing Media

In this guide you'll learn how to transcribe a media file

Prerequisites

• You must have an OAuth Client ID & Secret

• You must have a user access token, obtainable via API Authentication

• You must have some media to upload, for example an MP3 (a sample is provided below)

• Your application must have the scopes:

  • write_media

  • write_transcriptions

51KB

steve_jobs.mp3

Download Sample MP3

Steps

Authenticate

You need an access token to follow the steps below, you can find out about how to obtain one in the API Authentication guide.

API Authentication

Create a media object

First we'll create a media object. This will be our reference for any files we upload to Google Cloud storage directly.

API Reference

You can go to the API reference on how to do this, below is an example in cURL:

curl -X "POST" "https://api.captioned.carescribe.io/medias" \
     -H 'Accept: application/vnd.captioned.v1' \
     -H 'Authorization: Bearer <access token>' \
     -H 'Content-Type: application/json;' \
     -d $'{
  "media": {
    "content_type": "audio/mpeg"
  }
}'

The response should look something like this:

{
  "data": {
    "id": "12345678-abcd-abcd-abcd-abcdef012345",
    "type": "media",
    "attributes": {
      "uuid": "12345678-abcd-abcd-abcd-abcdef012345",
      "signed_url_for_upload": "https://storage.googleapis.com/<some_signed_path>"
    }
  }
}

The important part we need next is the signed_url_for_upload in the next request we'll do a PUT request to this URL.

Upload your media

Now that we have a URL for uploading we can upload our MP3.

API Reference

You can go to the API reference on how to do this, below is an example in cURL. You'll need to supply the same Content-Type header as you did when you created the media object.

curl 'https://storage.googleapis.com/<path from create media>' \
-X PUT \
-H 'Content-Type: audio/mpeg' \
--data-binary "@steve_jobs.mp3"

Note: The above cURL command will only work if it is run in the same directory as the steve_jobs.mp3 file.

If that was successful you'll get an empty body response with a 200 OK status code.

Create a transcription

Lastly, now the media has been uploaded we'll use it to create a transcription.

API Reference

You can go to the API reference on how to do this, below is an example in cURL.

curl -X "POST" "https://api.captioned.carescribe.io/transcriptions" \
     -H 'Accept: application/vnd.captioned.v1' \
     -H 'Authorization: Bearer <access token>' \
     -H 'Content-Type: application/json;' \
     -d $'{
  "source": {
    "type": "media",
    "url": "12345678-abcd-abcd-abcd-abcdef012345"
  }
}'

Note the JSON body should contain a top-level object with key of source where the value is an object containing two keys:

• type which must have the value media

• id which must have the ID of media that you created before

If this is successful you should receive a 201 Created status and response that looks like the following:

{
  "data": {
    "id": null,
    "type": "transcription",
    "attributes": {
      "id": 1769
    },
    "relationships": {
      "transcript_result": {
        "data": null
      },
      "transcription_sessions": {
        "data": [
          {
            "id": "34111",
            "type": "transcription_session"
          }
        ]
      }
    }
  }
}

You're all done!

If you've reached this step you have successfully transcribed some media and it will show within your account.