Octopus - C API

API Reference for the Octopus C SDK.

pv_octopus_t

typedef struct pv_octopus pv_octopus_t;

Container representing the Octopus Speech-to-Index engine.

pv_octopus_match_t

typedef struct {
    float start_sec;
    float end_sec;
    float probability;
} pv_octopus_match_t;

Container representing a matched utterance.

pv_octopus_init()

pv_status_t pv_octopus_init(
        const char *access_key,
        const char *model_path,
        pv_octopus_t **object);

Create a Octopus instance. Resources should be cleaned when you are done using the pv_octopus_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_octopus_t * * : Constructed instance of Octopus.

Returns

pv_status_t : Status code.

pv_octopus_delete()

void pv_octopus_delete(pv_octopus_t *object);

Releases resources acquired by Octopus.

Parameters

object pv_octopus_t * : Picovoice object.

pv_octopus_index()

pv_status_t pv_octopus_index(
    pv_octopus_t *object,
    const int16_t *pcm,
    int32_t num_samples,
    void **indices,
    int32_t *num_indices_bytes);

Indexes audio data. The audio needs to have a sample rate equal to pv_sample_rate() and be 16-bit linearly-encoded. This function operates on single-channel audio.

Parameters

object pv_octopus_t * : Octopus object.
pcm int16_t : Audio data.
num_samples int32_t : Number of audio samples to process.
indices void * * : Index metadata.
num_indices_bytes int32_t * : Size of index metadata in bytes.

Returns

pv_status_t : Status code.

pv_octopus_index_file()

pv_status_t pv_octopus_index_file(
    pv_octopus_t *object,
    const char *path,
    void **indices,
    int32_t *num_indices_bytes);

Indexes an audio file.

Parameters

object pv_octopus_t * : Octopus object.
path const char * : Absolute path to the audio file.
indices void * * : Index metadata.
num_indices_bytes int32_t * : Size of index metadata in bytes.

Returns

pv_status_t : Status code.

pv_octopus_search()

pv_status_t pv_octopus_search(
    pv_octopus_t *object,
    const void *indices,
    int32_t num_indices_bytes,
    const char *phrase,
    pv_octopus_match_t **matches,
    int32_t *num_matches);

Searches index metadata for occurrences of a given phrase.

Parameters

object pv_octopus_t * : Octopus object.
indices void * : Index metadata.
num_indices_bytes int32_t : Size of index metadata in bytes.
phrase const char * : Search phrase.
matches pv_octopus_match_t * * : Utterances matching the search phrase.
num_matches int32_t * : Numbers of matched utterances.

Returns

pv_status_t : Status code.

pv_octopus_version()

const char *pv_octopus_version(void);

Getter for version.

Returns

const char * : Octopus version.

pv_sample_rate()

int32_t pv_sample_rate(void);

Audio sample rate accepted by Octopus.

Returns

int32_t : Sample rate.

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.