media_c_api.h

Go to the documentation of this file.

/* Copyright 2021 ID R&D Inc. All Rights Reserved. */

#pragma once

#include <stdint.h>
#include <stddef.h>

#include <voicesdk/core/core_c_api.h>

#ifdef __cplusplus
extern "C" {
#endif

// forward declarations
typedef struct VoiceSdkSpeechSummaryEngine VoiceSdkSpeechSummaryEngine;
typedef struct VoiceSdkSpeechSummaryStream VoiceSdkSpeechSummaryStream;
typedef struct VoiceSdkSpeechSummaryStreamOpus VoiceSdkSpeechSummaryStreamOpus;
typedef struct VoiceSdkSnrComputer VoiceSdkSnrComputer;
typedef struct VoiceSdkSpeechEndpointDetector VoiceSdkSpeechEndpointDetector;
typedef struct VoiceSdkSpeechEndpointDetectorOpus VoiceSdkSpeechEndpointDetectorOpus;
typedef struct VoiceSdkQualityCheckEngine VoiceSdkQualityCheckEngine;

// api objects
typedef struct VoiceSdkSpeechEvent {
    bool is_voice;

    VoiceSdkAudioInterval audio_interval;
} VoiceSdkSpeechEvent;

typedef struct VoiceSdkSpeechInfo {
    float speech_length_ms;

    float background_length_ms;

    float total_length_ms;
} VoiceSdkSpeechInfo;

DECL_TYPED_ARRAY(VoiceSdkSpeechEventArray, VoiceSdkSpeechEvent)
DECL_TYPED_ARRAY(VoiceSdkSpeechInfoArray, VoiceSdkSpeechInfo)

typedef struct VoiceSdkSpeechSummary {
    VoiceSdkSpeechEventArray speech_events;

    VoiceSdkSpeechInfo speech_info;
} VoiceSdkSpeechSummary;

typedef enum VoiceSdkQualityCheckShortDescription {
    kVoiceSdkQualityCheckShortDescriptionTooNoisy = 0,

    kVoiceSdkQualityCheckShortDescriptionTooSmallSpeechLength = 1,

    kVoiceSdkQualityCheckShortDescriptionOk = 2,

    kVoiceSdkQualityCheckShortDescriptionTooSmallSpeechRelativeLength = 3,

    kVoiceSdkQualityCheckShortDescriptionMultipleSpeakersDetected = 4
} VoiceSdkQualityCheckShortDescription;

typedef enum VoiceSdkQualityCheckScenario {
    kVoiceSdkQualityCheckScenarioVerifyTiEnrollment = 0,

    kVoiceSdkQualityCheckScenarioVerifyTiVerification = 1,

    kVoiceSdkQualityCheckScenarioVerifyTdEnrollment = 2,

    kVoiceSdkQualityCheckScenarioVerifyTdVerification = 3,

    kVoiceSdkQualityCheckScenarioLiveness = 4
} VoiceSdkQualityCheckScenario;

typedef struct VoiceSdkQualityCheckMetricsThresholds {
    float minimum_snr_db;

    float minimum_speech_length_ms;

    float minimum_speech_relative_length;

    float maximum_multiple_speakers_detector_score;
} VoiceSdkQualityCheckMetricsThresholds;

typedef struct VoiceSdkQualityCheckEngineResult {
    VoiceSdkQualityCheckShortDescription quality_check_short_description;

    float snr_db;

    float speech_length_ms;

    float speech_relative_length;

    float multiple_speakers_detector_score;
} VoiceSdkQualityCheckEngineResult;

/************************
 * Speech Summary calls *
 ************************/

VOICE_SDK_API
VoiceSdkSpeechSummaryEngine* VoiceSdkSpeechSummaryEngineCreate(const char* init_data_path, char** error_msg);

VOICE_SDK_API
VoiceSdkSpeechSummary* VoiceSdkSpeechSummaryEngineGetSpeechSummaryFromBytes(const VoiceSdkSpeechSummaryEngine* engine,
                                                                            const uint8_t* bytes, size_t bytes_num,
                                                                            size_t sample_rate, char** error_msg);

VOICE_SDK_API
VoiceSdkSpeechSummary* VoiceSdkSpeechSummaryEngineGetSpeechSummaryFromPcm16Samples(
        const VoiceSdkSpeechSummaryEngine* engine, const int16_t* pcm16_samples, size_t samples_num, size_t sample_rate,
        char** error_msg);

VOICE_SDK_API
VoiceSdkSpeechSummary* VoiceSdkSpeechSummaryEngineGetSpeechSummaryFromFloatSamples(
        const VoiceSdkSpeechSummaryEngine* engine, const float* float_samples, size_t samples_num, size_t sample_rate,
        char** error_msg);

VOICE_SDK_API
VoiceSdkSpeechSummary* VoiceSdkSpeechSummaryEngineGetSpeechSummaryFromFile(const VoiceSdkSpeechSummaryEngine* engine,
                                                                           const char* audio_path, char** error_msg);

VOICE_SDK_API
void VoiceSdkSpeechSummaryEngineRelease(VoiceSdkSpeechSummaryEngine* engine);


VOICE_SDK_API
void VoiceSdkSpeechSummaryRelease(VoiceSdkSpeechSummary* summary);


/*******************************
 * SpeechSummaryStream calls   *
 *******************************/

VOICE_SDK_API
VoiceSdkSpeechSummaryStream* VoiceSdkSpeechSummaryStreamCreate(const VoiceSdkSpeechSummaryEngine* engine,
                                                               size_t sample_rate, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamAddByteSamples(const VoiceSdkSpeechSummaryStream* stream, const uint8_t* bytes,
                                               size_t bytes_num, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamAddPcm16Samples(const VoiceSdkSpeechSummaryStream* stream, const int16_t* pcm16_samples,
                                                size_t samples_num, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamAddFloatSamples(const VoiceSdkSpeechSummaryStream* stream, const float* float_samples,
                                                size_t samples_num, char** error_msg);


VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamGetCurrentBackgroundLength(const VoiceSdkSpeechSummaryStream* stream, float* result,
                                                           char** error_msg);
VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamHasSpeechEvents(const VoiceSdkSpeechSummaryStream* stream, bool* result,
                                                char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamGetSpeechEvent(const VoiceSdkSpeechSummaryStream* stream, VoiceSdkSpeechEvent* result,
                                               char** error_msg);

VOICE_SDK_API
VoiceSdkSpeechSummary* VoiceSdkSpeechSummaryStreamGetTotalSpeechSummary(const VoiceSdkSpeechSummaryStream* stream,
                                                                        char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamGetTotalSpeechInfo(const VoiceSdkSpeechSummaryStream* stream,
                                                   VoiceSdkSpeechInfo* result, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamReset(const VoiceSdkSpeechSummaryStream* stream, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamFinalize(const VoiceSdkSpeechSummaryStream* stream, char** error_msg);

VOICE_SDK_API
void VoiceSdkSpeechSummaryStreamRelease(VoiceSdkSpeechSummaryStream* stream);

/***********************************
 * SpeechSummaryStreamOpus calls   *
 ***********************************/

VOICE_SDK_API
VoiceSdkSpeechSummaryStreamOpus* VoiceSdkSpeechSummaryStreamOpusCreate(const char* init_data_path, size_t sample_rate,
                                                                       char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamOpusAddPacket(const VoiceSdkSpeechSummaryStreamOpus* stream, const uint8_t* bytes,
                                              size_t bytes_num, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamOpusGetCurrentBackgroundLength(const VoiceSdkSpeechSummaryStreamOpus* stream,
                                                               float* result, char** error_msg);
VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamOpusHasSpeechEvents(const VoiceSdkSpeechSummaryStreamOpus* stream, bool* result,
                                                    char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamOpusGetSpeechEvent(const VoiceSdkSpeechSummaryStreamOpus* stream,
                                                   VoiceSdkSpeechEvent* result, char** error_msg);

VOICE_SDK_API
VoiceSdkSpeechSummary* VoiceSdkSpeechSummaryStreamOpusGetTotalSpeechSummary(
        const VoiceSdkSpeechSummaryStreamOpus* stream, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamOpusGetTotalSpeechInfo(const VoiceSdkSpeechSummaryStreamOpus* stream,
                                                       VoiceSdkSpeechInfo* result, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamOpusReset(const VoiceSdkSpeechSummaryStreamOpus* stream, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechSummaryStreamOpusFinalize(const VoiceSdkSpeechSummaryStreamOpus* stream, char** error_msg);

VOICE_SDK_API
void VoiceSdkSpeechSummaryStreamOpusRelease(VoiceSdkSpeechSummaryStreamOpus* stream);

/************************
 * SNR Computer calls   *
 ************************/

VOICE_SDK_API
VoiceSdkSnrComputer* VoiceSdkSnrComputerCreate(const char* init_data_path, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSnrComputerComputeFromBytes(const VoiceSdkSnrComputer* engine, const uint8_t* bytes, size_t bytes_num,
                                         size_t sample_rate, float* result, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSnrComputerComputeFromPcm16Samples(const VoiceSdkSnrComputer* engine, const int16_t* pcm16_samples,
                                                size_t samples_num, size_t sample_rate, float* result,
                                                char** error_msg);

VOICE_SDK_API
bool VoiceSdkSnrComputerComputeFromFloatSamples(const VoiceSdkSnrComputer* engine, const float* float_samples,
                                                size_t samples_num, size_t sample_rate, float* result,
                                                char** error_msg);

VOICE_SDK_API
bool VoiceSdkSnrComputerComputeFromFile(const VoiceSdkSnrComputer* engine, const char* audio_path, float* result,
                                        char** error_msg);

VOICE_SDK_API
void VoiceSdkSnrComputerRelease(VoiceSdkSnrComputer* engine);

/********************************
 * SpeechEndpointDetector calls *
 ********************************/

VOICE_SDK_API
VoiceSdkSpeechEndpointDetector* VoiceSdkSpeechEndpointDetectorCreate(size_t min_speech_length_ms,
                                                                     size_t max_silence_length_ms, size_t sample_rate,
                                                                     char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorAddByteSamples(const VoiceSdkSpeechEndpointDetector* detector, const uint8_t* bytes,
                                                  size_t bytes_num, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorAddPcm16Samples(const VoiceSdkSpeechEndpointDetector* detector,
                                                   const int16_t* pcm16_samples, size_t samples_num, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorAddFloatSamples(const VoiceSdkSpeechEndpointDetector* detector,
                                                   const float* float_samples, size_t samples_num, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorIsSpeechEnded(const VoiceSdkSpeechEndpointDetector* detector, bool* result,
                                                 char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorReset(const VoiceSdkSpeechEndpointDetector* detector, char** error_msg);

VOICE_SDK_API
void VoiceSdkSpeechEndpointDetectorRelease(VoiceSdkSpeechEndpointDetector* detector);

/************************************
 * SpeechEndpointDetectorOpus calls *
 ************************************/

VOICE_SDK_API
VoiceSdkSpeechEndpointDetectorOpus* VoiceSdkSpeechEndpointDetectorOpusCreate(size_t min_speech_length_ms,
                                                                             size_t max_silence_length_ms,
                                                                             size_t sample_rate, char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorOpusAddPacket(const VoiceSdkSpeechEndpointDetectorOpus* detector,
                                                 const uint8_t* bytes, size_t bytes_num, char** error_msg);
VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorOpusIsSpeechEnded(const VoiceSdkSpeechEndpointDetectorOpus* detector, bool* result,
                                                     char** error_msg);

VOICE_SDK_API
bool VoiceSdkSpeechEndpointDetectorOpusReset(const VoiceSdkSpeechEndpointDetectorOpus* detector, char** error_msg);

VOICE_SDK_API
void VoiceSdkSpeechEndpointDetectorOpusRelease(VoiceSdkSpeechEndpointDetectorOpus* detector);

/************************************
 * VoiceSdkQualityCheckEngine calls *
 ************************************/

VOICE_SDK_API
VoiceSdkQualityCheckEngine* VoiceSdkQualityCheckEngineCreate(const char* init_data_path, VoiceSdkErrorCode* error_code,
                                                             char** error_msg);

VOICE_SDK_API
bool VoiceSdkQualityCheckEngineGetRecommendedThresholds(const VoiceSdkQualityCheckEngine* engine,
                                                        VoiceSdkQualityCheckScenario scenario,
                                                        VoiceSdkQualityCheckMetricsThresholds* thresholds,
                                                        VoiceSdkErrorCode* error_code, char** error_msg);

VOICE_SDK_API
VoiceSdkQualityCheckEngineResult* VoiceSdkQualityCheckEngineCheckQualityAudioFile(
        const VoiceSdkQualityCheckEngine* engine, const char* audio_path,
        VoiceSdkQualityCheckMetricsThresholds thresholds, VoiceSdkErrorCode* error_code, char** error_msg);

VOICE_SDK_API
VoiceSdkQualityCheckEngineResult* VoiceSdkQualityCheckEngineCheckQualityFloatSamples(
        const VoiceSdkQualityCheckEngine* engine, const float* float_samples, size_t num_samples, size_t sample_rate,
        VoiceSdkQualityCheckMetricsThresholds thresholds, VoiceSdkErrorCode* error_code, char** error_msg);

VOICE_SDK_API
VoiceSdkQualityCheckEngineResult* VoiceSdkQualityCheckEngineCheckQualityPcm16Samples(
        const VoiceSdkQualityCheckEngine* engine, const int16_t* samples, size_t num_samples, size_t sample_rate,
        VoiceSdkQualityCheckMetricsThresholds thresholds, VoiceSdkErrorCode* error_code, char** error_msg);

VOICE_SDK_API
VoiceSdkQualityCheckEngineResult* VoiceSdkQualityCheckEngineCheckQualityBytes(
        const VoiceSdkQualityCheckEngine* engine, const uint8_t* bytes, size_t num_bytes, size_t sample_rate,
        VoiceSdkQualityCheckMetricsThresholds thresholds, VoiceSdkErrorCode* error_code, char** error_msg);

VOICE_SDK_API
void VoiceSdkQualityCheckEngineResultRelease(VoiceSdkQualityCheckEngineResult* check_result);

VOICE_SDK_API
void VoiceSdkQualityCheckEngineRelease(VoiceSdkQualityCheckEngine* engine);

#ifdef __cplusplus
}
#endif