Using Audio API

curl --request POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/upload?tag=helpful-tag --data-binary "@/path/to/your/audio.wav" 

{
    "success": true,
    "audio_id": "313f6795-df6d-4ffa-ba86-7b98f07b4a8d"
}

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/313f6795-df6d-4ffa-ba86-7b98f07b4a8d/info 

{
    "success": true,
    "audio_id": "313f6795-df6d-4ffa-ba86-7b98f07b4a8d",
    "tag": "helpful-tag",
    "ts_created": 1526337362,
    "channels": 2,
    "samplerate": 48000,
    "format": "WAV",
    "frames": 960000,
    "duration": 20
}

curl --remote-name --remote-header-name -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/313f6795-df6d-4ffa-ba86-7b98f07b4a8d/download

curl --remote-name --remote-header-name -H "Authorization: Bearer <your_api_token>" "https://api-dev.headspin.io/v0/audio/313f6795-df6d-4ffa-ba86-7b98f07b4a8d/download?channels=mono"

curl --remote-name --remote-header-name -H "Authorization: Bearer <your_api_token>" "https://api-dev.headspin.io/v0/audio/313f6795-df6d-4ffa-ba86-7b98f07b4a8d/download?channels=left&start=2" 

curl --remote-name --remote-header-name "https://<your_api_token>@api-dev.headspin.io/v0/audio/313f6795-df6d-4ffa-ba86-7b98f07b4a8d/download?channels=right&start=3.14&end=15.456"

curl -X DELETE -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/313f6795-df6d-4ffa-ba86-7b98f07b4a8d/delete 

{
    "success": true
}

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/list?tag=helpful-tag 

{
    "audio_ids": [
        "9e22786d-f7df-4c4a-b601-384bc2b06ae9",
        "5eca0c4c-f54f-49f6-9d03-64db261b7e23"
    ],
    "success": true
}

curl -X GET -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/list --data-urlencode "tag=%help%" 

{
    "audio_ids": [
        "9e22786d-f7df-4c4a-b601-384bc2b06ae9",
        "5eca0c4c-f54f-49f6-9d03-64db261b7e23"
    ],
    "success": true
}

{
    "hostname": "host.headspin.io",
    "audio_ids": [
        "6fd55663-0aa4-416e-a752-cfab81a13701",
        "6c63cccb-5914-414c-96f5-fd9234147102",
        "375051e0-01e6-4dbb-9e4b-017a411ab7c6"
    ]
}

curl --request POST -H "Authorization: Bearer <your_api_token>"  https://api-dev.headspin.io/v0/audio/prepare --data '{"hostname": "host.headspin.io", "audio_ids": ["6fd55663-0aa4-416e-a752-cfab81a13701", "6c63cccb-5914-414c-96f5-fd9234147102", "375051e0-01e6-4dbb-9e4b-017a411ab7c6"]}' 

{
    "success": false,
    "audio_ids": {
        "6fd55663-0aa4-416e-a752-cfab81a13701": "cached",
        "6c63cccb-5914-414c-96f5-fd9234147102": "cached",
        "375051e0-01e6-4dbb-9e4b-017a411ab7c6": "error"
    }
}

{
    "device_address": "my_device@host.headspin.io",
    "audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701"
}

curl --request POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/inject/start --data '{"device_address": "my_device@host.headspin.io", "audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701"}' 

{
    "success": true,
    "worker_id": "6c7d6c1b27a147a2af48be263ea9a517"
}

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/inject/6c7d6c1b27a147a2af48be263ea9a517/status

{
    "success": true,
    "finished": false,
    "hostname": "host.headspin.io",
    "device_id": "my_device",
    "audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701",
    "start_time": 1524884246,
    "end_time": null,
    "inject": {
        "state": "working"
    }
}

{
    "success": true,
    "finished": true,
    "hostname": "host.headspin.io",
    "device_id": "my_device",
    "audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701",
    "start_time": 1524884246,
    "end_time": 1524884557,
    "inject": {
        "state": "finished"
    }
}

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/inject/6c7d6c1b27a147a2af48be263ea9a517/wait 

{
    "success": true,
    "finished": true,
    "hostname": "host.headspin.io",
    "device_id": "my_device",
    "audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701",
    "start_time": 1524884246,
    "end_time": 1524884557,
    "inject": {
        "state": "finished"
    }
}

curl --request POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/inject/6c7d6c1b27a147a2af48be263ea9a517/stop 

{
    "success": true
}

{
    "device_address": "my_device@host.headspin.io",
    "max_duration": 300,
    "tag": "a helpfully descriptive tag"
}

curl --request POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/capture/start --data '{"device_address": "my_device@host.headspin.io", "max_duration": 300, "tag": "a helpfully descriptive tag"}' 

{
    "success": true,
    "worker_id": "139a1bbc22304dda8cbb7c6085c43580"
}

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/capture/139a1bbc22304dda8cbb7c6085c43580/status 

{
    "success": true,
    "finished": false,
    "hostname": "host.headspin.io",
    "device_id": "my_device",
    "audio_id": null,
    "start_time": 1524884246,
    "max_duration": 300,
    "end_time": null,
    "capture": {
        "state": "working"
    },
    "upload": {
        "state": "waiting"
    }
}

{
    "success": true,
    "finished": true,
    "hostname": "host.headspin.io",
    "device_id": "my_device",
    "audio_id": "db34e55a-e996-4dd5-85bf-d7682630932d",
    "start_time": 1524884246,
    "end_time": 1524884546,
    "capture": {
        "state": "finished"
    },
    "upload": {
        "state": "working"
    }
}

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/capture/139a1bbc22304dda8cbb7c6085c43580/wait 

{
    "success": true,
    "finished": true,
    "hostname": "host.headspin.io",
    "device_id": "my_device",
    "audio_id": "db34e55a-e996-4dd5-85bf-d7682630932d",
    "start_time": 1524884246,
    "end_time": 1524884546,
    "capture": {
        "state": "finished"
    },
    "upload": {
        "state": "working"
    }
}

curl --request POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/capture/139a1bbc22304dda8cbb7c6085c43580/stop

{
    "success": true
}

• test_audio_id: audio_id of the test.
• ref_audio_id: audio_id of the reference.
• match_status_thresholds: (optional) A JSON object with the following keys:
  • full: Threshold used for determining full match status.
    • match_score: Must be a value between 0 and 1.
    • prominence_ratio: Must be a value >= 1. See Response Explained below for more details.
  • partial: Thresholds used for determining partial match status. Must meet both thresholds to be partial match.
    • match_score: Must be a value between 0 and 1 and smaller than the threshold used for full match.
    • prominence_ratio: Must be a value >= 1. See Response Explained below for more details.

{
    "full": {"match_score": 0.9, "prominence_ratio": 1.0},
    "partial": {"match_score": 0.4, "prominence_ratio": 1.5}
}

{
    "test_audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701",
    "ref_audio_id": "6c63cccb-5914-414c-96f5-fd9234147102"
}

{
    "test_audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701",
    "ref_audio_id": "6c63cccb-5914-414c-96f5-fd9234147102",
    "match_status_thresholds": {
        "full": {"match_score": 0.8, "prominence_ratio": 1.0},
        "partial": {"match_score": 0.5, "prominence_ratio": 1.3}
    }
}

curl --request POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/audio/analysis/match --data '{"test_audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701", "ref_audio_id": "6c63cccb-5914-414c-96f5-fd9234147102"}' 

{
    "success": false,
    "error_message": "empty test audio",
    "test_audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701",
    "ref_audio_id": "6c63cccb-5914-414c-96f5-fd9234147102"
}

• success: Returns false since the analysis could not run on the provided audio ids after inspecting the audio.

• error_msg: Reason for why the analysis could not run.

  • Returns empty <test | ref> audio if the test or reference audio is completely devoid of sound waves. Returns empty test audio, empty ref audio if both audio are empty.
    
  • Returns audio size too large for analysis if the durations of the audio files are too long. We recommend that the test audio be shorter than 5 minutes and the reference audio shorter than 40 seconds. You can slice out segments from the audio files to shorten the audio durations.
    

{
    "success": true,
    "version": "0.1.0",
    "test_audio_id": "6fd55663-0aa4-416e-a752-cfab81a13701",
    "parameters": {
        "sr_at_analysis": 8000,
        "nfft": 512,
        "match_status_thresholds": {
            "full": {"match_score": 0.9, "prominence_ratio": 1.0},
            "partial": {"match_score": 0.4, "prominence_ratio": 1.5}
        }
    },
    "result": {
        "6c63cccb-5914-414c-96f5-fd9234147102": {
            "match_status": "no",
            "match_score": 0.139,
            "prominence_ratio": 1.013,
            "start_time": null,
            "end_time": null,
            "precision_status": "medium",
            "poverlap": 0.625,
            "error_msg": null,
            "analysis_processing_time": 9.824
        }
    }
}

• success: Returns true since the analysis successfully completed on the provided audio ids (regardless of match_status).

• parameters:

  • sr_at_analysis: Sampling rate to which reference and test are resampled before analysis. Set at 8000.
  • nfft: The number of samples used in each block for Fast Fourier Transform (FFT). Set at 512.
  • match_status_thresholds:
    • full:
      • match_score: Match score threshold for full match. Defaults to 0.9.
      • prominence_ratio: Prominence ratio threshold for full match. Defaults to the minimum possible value of 1 (full match status is determined purely from match_score).
    • partial:
      • match_score: Match score threshold for partial match. Defaults to 0.4.*
      • prominence_ratio: Prominence ratio threshold for partial match. Defaults to 1.5.*

  *Returns partial match in match_status only if conditions are met on both thresholds.
  E.g., under the default settings, if match_score is 0.5 but prominence_ratio is 1.0, then this is classified as no match.

• result:

  • match_status | full, partial, no, or error: Status of match as set by match_score and the thresholds.
    Returns error if precision_status is critically low or if the reference is not contained in the test (start_time or end_time is null).

  • match_score | 0 <= match_score <= 1: Quality of match when best aligned (max correlation coefficient).

  • prominence_ratio | >= 1: Quality of match relative to noise (ratio of the max correlation coefficient to the 2nd max).
    This number is ~1 if there is no match, but can also be ~1 if there is a match and the reference is repeated in the test.
    Because prominence_ratio is the ratio of the max correlation coefficient to the second max, the minimum possible value is 1.

  • start_time | sec or null: Start time (in seconds) of the reference in terms of the test (at best alignment).
    Returns null if match_status is no (when there is no match).
    Also returns null if start_time < 0 (i.e., reference starts before the test & therefore not contained in the test), in which case match_status is set as error.

  • end_time | sec or null: End time (in seconds) of the reference in terms of the test (at best alignment).
    Returns null if match_status is no (when there is no match).
    Also returns null if end_time exceeds the duration of the test (i.e., reference is not contained in the test), in which case match_status is set as error.

  • precision_status | high, medium, low, or critically low: Status of precision as set by poverlap.
    Returns critically low if poverlap drops below 0.25 which also sets match_status as error.

  • poverlap: 0 <= poverlap <= 0.9: % of overlap used between FFT blocks.
    Based on the size of the reference and the test, this parameter is automatically adjusted to keep the analysis processing time under ~10s.
    You can compare to the initial value of 0.9 to see how much precision has dropped.

  • error_msg: Reason(s) for match_status returning error.
    Returns reference is out of bounds if either start_time or end_time is null due to the reference not being contained in the test.
    Returns precision is too low if precision_status is critically low.
    If both conditions are met, then both error messages are displayed.