Audio File Specification

KV ingests a single recorded voice sample of a patient speaking and outputs a single prediction based on vocal features predicted using machine learning technology. Different audio file types (e.g., MP3 or M4A) and other audio characteristics, such as sampling rate, can impact the amount of information, in the form of sound waves, that is available. Because KV evaluates signals or features at specific frequencies, compressing audio files, capturing them in a noisy environment, or at a low frequency can degrade important information necessary to make accurate predictions using KV.

To ensure that KV provides your clinical team with the most accurate insights, we have set up automatic audio guardrails that will prevent prediction issuing for audio files that fail to meet any of the audio specifications outlined below

To help us continue to improve our technology's performance, Submit Feedback.

Type

WAV

WAV files minimize compression. Ideally, users record audio files in WAV format to capture the vocal signal appropriately. Users can convert audio files to WAV format if they originally recorded audio in a different file format.

Sample Rate

8 kHz

This is the session identifier that you receive when you successfully iThe sample rate refers to the number of audio samples recorded per second. The higher the sample rate, the more vocal signals will be captured, which may improve KV’s accuracy. The 8 kHz represents the minimum sample rate. Higher sample rates are accepted and recommended when possible.nitiate the session using the “Initiate” endpoint.

Channel

Channel Separated (Single Channel)

Capture audio such that the voice of the medical professional and the voice of the patient are on a separate audio channel. The channel recording the patient’s audio is submitted. KV cannot distinguish between the patient and the medical provider.

Voice Content

30 seconds

KV requires sufficient vocal signal to make a reasonably reliable prediction. Patient speech content should be at least 30 seconds in duration. Speech content is distinct from audio file length. The uploaded file will likely exceed 30 seconds to meet this requirement.

Sample code of the complete flow


const axios = require('axios'); 
const FormData = require('form-data'); 
const fs = require('fs'); 

const URL_ROOT = "https://api.kintsugihello.com/" 
// Initiate endpoint URL.
const URL_INITIATE = new URL('/v1/initiate', URL_ROOT) 
// Predict endpoint URL. 
const URL_PREDICT = new URL('/v1/predict/server/depression/binary', URL_ROOT) 
// Feedback endpoint URL. 
const URL_FEEDBACK = new URL ('/v1/feedback/server/depression/binary', URL_ROOT) 

async function initiate(api_key) {
    console.log('Start initiate!')
    let data = new FormData();
    data.append('user_id', 'USER_ID');
    data.append('is_initiated', 'true');
    let config = {
        method: 'post',
        url: URL_INITIATE,
        headers: {
            'X-API-Key': api_key,
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete initiate! session_id: ' + response.data.session_id)
    return response.data.session_id
}

async function predict(session_id) {
    console.log('Start predict!')
    let data = new FormData();
    data.append('session_id', session_id);
    data.append('file', fs.createReadStream('Sub_PHQ0_GAD0_I.wav'));
    let config = {
        method: 'post',
        url: URL_PREDICT,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete predict! data: ' + JSON.stringify(response.data))
}

async function feedback(session_id) {
    console.log('Start feedback!')
    let data = new FormData();
    data.append('session_id', session_id);
    // Available options of actual score are: true, false,
    // additional_consideration_required.
    // Feedback endpoint do not return any data.
    data.append('actual_score', 'true');
    let config = {
        method: 'patch',
        url: URL_FEEDBACK,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    await axios.request(config)
    console.log('Complete feedback!')
}

async function main() {
    let session_id = await initiate("API_KEY")
    await predict(session_id)
    await feedback(session_id)
}

main().then((data) => {
    console.log("Finish!")
}).catch((error) => {
    console.log(error.message)
});


const axios = require('axios'); 
const FormData = require('form-data'); 
const fs = require('fs'); 

const URL_ROOT = "https://api.kintsugihello.com/" 
// Initiate endpoint URL.
const URL_INITIATE = new URL('/v1/initiate', URL_ROOT) 
// Predict endpoint URL. 
const URL_PREDICT = new URL('/v1/predict/server/depression/binary', URL_ROOT) 
// Feedback endpoint URL. 
const URL_FEEDBACK = new URL ('/v1/feedback/server/depression/binary', URL_ROOT) 

async function initiate(api_key) {
    console.log('Start initiate!')
    let data = new FormData();
    data.append('user_id', 'USER_ID');
    data.append('is_initiated', 'true');
    let config = {
        method: 'post',
        url: URL_INITIATE,
        headers: {
            'X-API-Key': api_key,
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete initiate! session_id: ' + response.data.session_id)
    return response.data.session_id
}

async function predict(session_id) {
    console.log('Start predict!')
    let data = new FormData();
    data.append('session_id', session_id);
    data.append('file', fs.createReadStream('Sub_PHQ0_GAD0_I.wav'));
    let config = {
        method: 'post',
        url: URL_PREDICT,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete predict! data: ' + JSON.stringify(response.data))
}

async function feedback(session_id) {
    console.log('Start feedback!')
    let data = new FormData();
    data.append('session_id', session_id);
    // Available options of actual score are: true, false,
    // additional_consideration_required.
    // Feedback endpoint do not return any data.
    data.append('actual_score', 'true');
    let config = {
        method: 'patch',
        url: URL_FEEDBACK,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    await axios.request(config)
    console.log('Complete feedback!')
}

async function main() {
    let session_id = await initiate("API_KEY")
    await predict(session_id)
    await feedback(session_id)
}

main().then((data) => {
    console.log("Finish!")
}).catch((error) => {
    console.log(error.message)
});


import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/binary",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

# *Binary: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/depression/binary",
    data={"session_id": session_id, "actual_score": "true"},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")


import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/severity",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")