Falcon Speaker Diarization
C API

API Reference for the Falcon C SDK.

pv_falcon_t

typedef struct pv_falcon pv_falcon_t;

Container representing the Falcon Speaker Diarization object.

pv_falcon_init()

pv_status_t pv_falcon_init(
        const char *access_key,
        const char *model_path,
        pv_falcon_t **object);

Creates a Falcon instance. Resources should be cleaned when you are done using the pv_falcon_delete() function.

Parameters

• access_key const char * : AccessKey obtained from Picovoice Console.
• model_path const char * : Absolute path to the file containing model parameters (.pv).
• object pv_falcon_t * * : Constructed instance of Falcon.

Returns

• pv_status_t : Status code.

pv_falcon_delete()

void pv_falcon_delete(pv_falcon_t *object);

Releases resources acquired by Falcon.

Parameters

• object pv_falcon_t * : Falcon object.

pv_falcon_process()

pv_status_t pv_falcon_process(
    pv_falcon_t *object,
    const int16_t *pcm,
    int32_t num_samples,
    int32_t *num_segments,
    pv_segment_t **segments);

Processes the given audio data and returns the diarization output.

This function analyzes the provided audio data, which should be single-channel, 16-bit linearly-encoded, and have a sample rate matching pv_sample_rate(). It identifies different segments in the audio, each represented by a pv_segment_t structure. The caller is responsible for freeing the segments buffer using pv_falcon_segments_delete().

Parameters

• object pv_falcon_t * : Falcon object.
• pcm int16_t : A frame of audio samples.
• num_samples int32_t : Number of audio samples to process.
• num_segments int32_t * : Number of segments in the output.
• segments pv_segment_t * * : Array of segments in the output.

Returns

• pv_status_t : Status code.

pv_falcon_process_file()

pv_status_t pv_falcon_process_file(
    pv_falcon_t *object,
    const char *audio_path,
    int32_t *num_segments,
    pv_segment_t **segments);

Processes the given audio file and returns the diarization output. The supported formats are: 3gp (AMR), FLAC, MP3, MP4/m4a (AAC), Ogg, WAV and WebM.

It identifies different segments in the audio, each represented by a pv_segment_t structure. The caller is responsible for freeing the segments buffer using pv_falcon_segments_delete().

Parameters

• object pv_falcon_t * : Falcon object.
• audio_path const char * : Absolute path to audio file.
• num_segments int32_t * : Number of segments in the output.
• segments pv_segment_t * * : Array of segments in the output.

Returns

• pv_status_t : Status code.

pv_falcon_segments_delete()

void pv_falcon_segments_delete(pv_segment_t *segments);

Deletes words returned from pv_falcon_process() or pv_falcon_process_file().

Parameters

• segments pv_segment_t * : Array of segments returned from pv_falcon_process() or pv_falcon_process_file().

pv_falcon_version()

const char *pv_falcon_version(void);

Getter for version.

Returns

• const char * : Falcon version.

pv_sample_rate()

int32_t pv_sample_rate(void);

Audio sample rate accepted by Falcon.

Returns

• int32_t : Sample rate.

pv_segment_t

typedef struct {
    float start_sec; /** Start time of the segment in seconds. */
    float end_sec; /** End time of the segment in seconds. */
    int32_t speaker_tag; /** Speaker tag identifier - a non-negative integer identifying unique speakers. */
} pv_segment_t;

Struct represents a segment along with its start, end, and the corresponding speaker tag.

pv_status_t

typedef enum {
    PV_STATUS_SUCCESS = 0,
    PV_STATUS_OUT_OF_MEMORY,
    PV_STATUS_IO_ERROR,
    PV_STATUS_INVALID_ARGUMENT,
    PV_STATUS_STOP_ITERATION,
    PV_STATUS_KEY_ERROR,
    PV_STATUS_INVALID_STATE,
    PV_STATUS_RUNTIME_ERROR,
    PV_STATUS_ACTIVATION_ERROR,
    PV_STATUS_ACTIVATION_LIMIT_REACHED,
    PV_STATUS_ACTIVATION_THROTTLED,
    PV_STATUS_ACTIVATION_REFUSED
} pv_status_t;

Status code enum.

pv_status_to_string()

const char *pv_status_to_string(pv_status_t status);

Parameters

• status int32_t : Status code.

Returns

• const char * : String representation of status code.

pv_get_error_stack()

pv_status_t pv_get_error_stack(
        char ***message_stack,
        int32_t *message_stack_depth);

If a function returns a failure (any pv_status_t other than PV_STATUS_SUCCESS), this function can be called to get a series of error messages related to the failure. This function can only be called only once per failure status on another function. The memory for message_stack must be freed using pv_free_error_stack.

Regardless of the return status of this function, if message_stack is not NULL, then message_stack contains valid memory. However, a failure status on this function indicates that future error messages may not be reported.

Parameters

• message_stack const char * * * : Array of messages relating to the failure. Messages are NULL terminated strings. The array and messages must be freed using pv_free_error_stack().
• message_stack_depth int32_t * : The number of messages in the message_stack array.

pv_free_error_stack()

void pv_free_error_stack(char **message_stack);

This function frees the memory used by error messages allocated by pv_get_error_stack().

Parameters

• message_stack const char * * : Array of messages relating to the failure.