API Documentation

Logo

A detailed guide and reference to API for Dementia and MCI Detection

View the Project on GitHub SpectrumInsights/API-Documentation

API Documentation for Dementia and MCI Detection

Table of Contents

Introduction

This document provides a comprehensive guide for integrating with the Spectrum Insights API, designed to detect symptoms of dementia and Mild Cognitive Impairment (MCI) based on a 6-second voice recording. The document details the process of submitting recordings, awaiting results, and interpreting the returned data.

Requirements

Workflow

Configuring Recording Parameters Locally

Before submitting a recording to our API, ensure that the recording is configured with the appropriate parameters on your side. This configuration is crucial for maintaining the quality and compatibility of the audio file with our analysis process.

Obligatory Audio Configuration:

Ensure your recording library or tool is set with the following parameters before creating the .wav file:

Parameter Description Recommended Value
encoder The audio encoding format. AudioEncoder.wav
sampleRate The sample rate of the audio recording in Hz. 44100
bitRate The bit rate of the audio recording in bits per second. 705600
numChannels The number of audio channels (mono or stereo). 1 (Mono)

These settings ensure that your audio recording is optimized for our API, facilitating accurate analysis.

Submitting a Recording

Once your audio file is properly configured and recorded, submit it to our API using the following endpoint:

Endpoint:

POST https://masterhandlerapi.spectruminsights.net/api/recording/recording

Description: Submit a .wav format recording. Receive a unique recording ID in response.

Headers:

Authorization: Bearer YOUR_TOKEN

Body:

Example Request:

POST /api/recording/recording/ HTTP/1.1
Host: masterhandlerapi.spectruminsights.net
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

{
  "age": 65,
  "sex_assigned_at_birth": "female",
  "sound_file": audioFile
}

Example Response:

{
  "recording_id": "12345",
  "status": "recording_submitted"
}

Awaiting Results

Endpoint:

GET https://masterhandlerapi.spectruminsights.net/api/recording/recording/api/recording/recording/{id}`

Description:

Periodically query this endpoint, replacing {id} with the received recording ID, until the status changes to results_ready.

Headers:

Authorization: Bearer YOUR_TOKEN

Example Request:

GET /api/recording/recording/12345 HTTP/1.1
Host: masterhandlerapi.spectruminsights.net
Authorization: Bearer YOUR_TOKEN

Example Response:

{
  "recording_id": "12345",
  "created_date": "2024-01-22T15:30:00Z",
  "is_ill": false,
  "is_ill_proba": 0.05,
  "is_ill_score": 9,
  "status": "results_ready",
  "wav_file_duration": 5.989206349206349,
  "wav_sampling_rate": 44100,
  "num_sound_objects": 59854,
  "num_points": 379452,
  "num_samples": 266398,
  "amp_plot_file_path": "https://masterhandlerapi.spectruminsights.net/api/recording/recording/12345/amp_plot",
  "tone_plot_file_path": "https://masterhandlerapi.spectruminsights.net/api/recording/recording/12345/tone_plot",
  "phase_plot_file_path": "https://masterhandlerapi.spectruminsights.net/api/recording/recording/12345/phase_plot",
  "diagnosis_explainers": [
    {
      "name": "Amplitude – Standard Deviation",
      "value": 0.0,
      "definition": "Amplitude – Standard Deviation",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Amplitude – Shimmer",
      "value": 0.0,
      "definition": "Amplitude – Shimmer",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Amplitude – Lean",
      "value": 0.0,
      "definition": "Amplitude – Lean",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Frequency – Standard Deviation",
      "value": 0.0,
      "definition": "Frequency – Standard Deviation",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Frequency – Jitter",
      "value": 0.791439,
      "definition": "Frequency – Jitter",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Frequency - Lean",
      "value": 0.0,
      "definition": "Frequency - Lean",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Phase – Standard Deviation",
      "value": 10.0,
      "definition": "Phase – Standard Deviation",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Phase – Drift",
      "value": 10.0,
      "definition": "Phase – Drift",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Sound Objects / Harmonics",
      "value": 4.0875,
      "definition": "Sound Objects / Harmonics",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Low Harmonics Energy",
      "value": 0.0,
      "definition": "Low Harmonics Energy",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Sub Harmonics Energy",
      "value": 0.0,
      "definition": "Sub Harmonics Energy",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Harmonic to Noise Ratio",
      "value": 0.0,
      "definition": "Harmonic to Noise Ratio",
      "min_value": 0,
      "max_value": 10
    },
    {
      "name": "Harmonics Tilt",
      "value": 10.0,
      "definition": "Harmonics Tilt",
      "min_value": 0,
      "max_value": 10
    }
  ],
  "result_explanation": {
    "healthy_share": 0.4508,
    "ill_share": 0.5492
  }
}

Response Structure

Each submission and status query will return a JSON response containing:

Detailed Descriptions of diagnosis_explainers Metrics

Possible response statuses:

Interpreting the is_ill_score

The value of is_ill_score determines the diagnosis:

Security and Authorization

Support and Contact

For technical issues or questions regarding integration, please contact our technical support team at Email Address

Note: This documentation is intended for clients aiming to integrate the Spectrum Insights API for dementia and MCI diagnostics. Please thoroughly test all functionalities in a development environment before deploying in a production setting.