JSON metadata

If you chose the JSON metadata format, one JSON file per audio file has to be uploaded.

Naming the JSON file

In order to link the audio to its metadata, it is expected to give them the same name. For example:

• a_first_audio.mp3 and a_first_audio.json
• a_second_audio.wav and a_second_audio.json
• a_third_audio.mp3 and a_third_audio.json

JSON file content

The minimum viable JSON file content must be:

{}

In this case, the current date and time of audio+metadata processing will be kept to set the date and time of the audio.

A full example might look like:

{
  "date": "2019-06-09T11:14:56Z",
  "contactLine": "+33601020304",
  "metadata": {
    "reconciliation_id": "123-abc-xyz"
  }
}

Each key of this example is described below.

Keys

Date and time of the audio

If you know the date of production of the audio, and you wish to set it, use the key date:

{
  "date": "2019-06-09T11:14:56Z"
}

See valid date and time formats requirements

Caller phone number

If the audio is from a phone call, you can provide the caller phone number using the E.164 standard:

{
  "date": "2019-06-09T11:14:56Z",
  "contactLine": "+33601020304"
}

Custom metadata

If you wish to pass on additional information, e.g. a reconciliation ID to link your data to ours, you can provide them in metadata as a key, value dictionary.

The following rules apply:

• You can provide up to 50 pieces of metadata,
• keys must be between 1 to 40 characters among alphamnumerical, underscore and hyphen,
• values are strings of 255 length maximum of any character, or null value.

For example:

{
  "metadata": {
    "reconciliation_id": "123-abc-xyz",
    "audio_duration": "1234",
    "original_audio_file": "https://my-cdn.acme-corp.fr/audios/audio.mp3"
  }
}

Once digested by our system, the values you've input in metadata will be made available to you in the payload of each Call in our Activate API.

Example by the code

If you have a directory with audio files, and you quickly want to generate their JSON metadata files, you can run the following bash script.

For each audio in a directory (you can configure the extension before running it), it will create a JSON file with the audio file name in metadata.original_file key. This data will be exposed by the Activate API, therefore easing the data reconciliation.

#!/usr/bin/env bash

EXTENSION="mp3"

for filename in `ls *.$EXTENSION`;
do
  base_filename="${filename%.$EXTENSION}"
  echo "{\"metadata\": {\"original_file\": \"$filename\"}}" > ${base_filename}.json
done;