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 'x-access-token: TOKEN' \
    -H 'Authorization: Bearer TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"link":"<LINK TO FILE>.json"}'

Here's an example of a text file response:

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

Here's an example of an audio file response:

{
  name: "<Your-File.mp3>",
  id: "clmgn7nkg50527f0mulbhwi6z8",
  fileType: "audio/mpeg",
  format: "mp3",
  link: "<LINK TO FILE>",
}

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 -L -X POST 'https://groovy.audioshake.ai/job/' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <TOKEN>' \
    --data-raw '{
      "metadata": {
        "format": "json",
        "name": "alignment",
        "language": "en"
      },
      "callbackUrl": "https://example.com/webhook/alignment",
      "assetId": "ghi789",
    }'

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 -L -X POST 'https://groovy.audioshake.ai/job/' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <TOKEN>' \
    --data-raw '{
      "metadata": {
        "format": "json",
        "name": "alignment",
        "language": "en"
      },
      "callbackUrl": "https://example.com/webhook/alignment",
      "assetId": "ghi789",
      "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 --request GET \
    --url https://groovy.audioshake.ai/job/[insert job ID here] \
    --header 'Authorization: Bearer [insert JWT token here]' \
    --header 'Content-Type: application/json'

The server will reply with an HTTP status code of 200 with a response that contains a "job" object.

{
  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: "transcription.json",
        id: "clksrg52j2319f7of26wleinn",
        fileType: "application/json",
        format: "json",
        link: "<LINK TO FILE>"
      }
    ]
  }
}