Alignment

Given an audio file and a transcription json file, AudioShake will map the transcribed text to the corresponding timestamps in the audiofile. However, this task may also be combined with transcription in a single call by uploading an audio file and requesting an alignment job.

Upload Files: Audio File and Text File

You can make a POST request to either the /upload/link or /upload endpoint to upload both audio and text files.

When using the /upload/link endpoint, you should send a JSON payload that includes a link to the audio file and the text file. Alternatively, you can use the more general /upload endpoint for uploading files directly from disk. Expect both endpoints to return a JSON payload containing an asset object with an "id".

curl -X 'POST' \
  'https://groovy.audioshake.ai/upload/link' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer EXAMPLE' \
  -H 'Content-Type: application/json' \
  -d '{
  "link": "https://link-to-your-file",
  "name": "audioshake-it-up"
}'

Here's an example of a text file response:

{
  name: "<Your-File.json>",
  id: "clkr0i2mh0155eyn38sa3g5eu",
  fileType: "application/json",
  format: "json",
  link: "<LINK TO FILE>"
}

Here's an example of an audio file response:

{
  "name": "audioshake-it-up",
  "id": "clyxaywtp00ne0jpi4nf435dv",
  "fileType": "audio/mpeg",
  "format": "mp3",
  "link": "YOUR_AUDIO_FILE_LINK"
}

Create a Job: Transcription + Alignment

Once you have the asset ID, you can create a job request to transcribe audio into readable text and then generate an alignment file that maps transcribed text to the corresponding timestamps in the audio file. The endpoint accepts a JSON request with the asset ID, a callback url, and a metadata object that contains a format and name that maps to the desired output. In the following example, we'll explicitly use alignment:

curl -X 'POST' \
  'https://groovy.audioshake.ai/job/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer EXAMPLE' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "format": "json",
    "name": "alignment",
    "language": "en"
  },
  "callbackUrl": "https://example.com/webhook/alignment",
  "assetId": "abc123"
}'

Create a Job: Alignment Only

Given an audio asset id and a text/json asset id, you can generate an alignment file that maps the provided text into a file with the corresponding timestamps in the audiofile. The endpoint accepts a JSON request with the file ID, audio file id, a callback url, and a metadata object that contains a format and name that maps to the desired output. In the following example, we'll explicitly use alignment:

curl -X 'POST' \
  'https://groovy.audioshake.ai/job/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer EXAMPLE' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "format": "json",
    "name": "alignment",
    "language": "en"
  },
  "callbackUrl": "https://example.com/webhook/alignment",
  "assetId": "abc123",
  "otherSourceAssets": [
    {
      "id": "xyz001",
      "type": "transcription",
      "name": "transcription"
    }
  ]
}'

Get Job

After you have created a job request, you can retrieve the results by making a GET request to the /jobs/{job_id} endpoint, where job_id is the ID of the job that you created. Here is an example of a curl command that retrieves the results of a job request:

curl -X 'GET' \
  'https://groovy.audioshake.ai/job/JOB_ID' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer EXAMPLE'

The server will reply with an HTTP status code of 200 with a response that contains a "job" object. To retrieve the output asset, parse the outputAssets list, and there should be an asset with name: "alignment.<format>" for singular requested format.

{
  job: {
    id: "clksrfob8000bf7of6xkscy8m",
    clientId: "<YOUR CLIENT ID>",
    createdAt: "2023-08-01T20:37:06.656Z",
    startedAt: "2023-08-01T20:37:07.839Z",
    updatedAt: "2023-08-01T20:37:28.392Z",
    requestId: "clksrfob8000bf7of6xkscy8m",
    licenseId: "<YOUR LICENSE ID>",
    metadata: {
      format: "json",
      name: "alignment",
      language: "en"
    },
    callbackUrl: "<YOUR CALLBACK URL>",
    status: "completed",
    statusInfo: {},
    sourceAsset: {
      name: "COOKIN-EUROPA_Drum.mp3",
      id: "clksq2o6c1506f7ofcyvzpdh8",
      fileType: "audio/mpeg",
      format: "mp3",
      link: "<LINK TO FILE>"
    },
    outputAssets: [
      {
        name: "alignment.json",
        id: "clksrg52j2319f7of26wleinn",
        fileType: "application/json",
        format: "json",
        link: "<LINK TO FILE>"
      }
    ]
  }
}