PvSpeaker
C API

API Reference for the PvSpeaker C SDK.

pv_speaker_t

typedef struct pv_speaker pv_speaker_t;

Struct representing the PvSpeaker object.

pv_speaker_init()

pv_speaker_status_t pv_speaker_init(
        int32_t sample_rate,
        int16_t bits_per_sample,
        int32_t buffer_size_secs,
        int32_t device_index,
        pv_speaker_t **object);

Creates a PvSpeaker instance. When finished with the instance, resources should be cleaned up using the pv_speaker_delete() function.

Parameters

• sample_rate int32_t : The sample rate of the audio to be played.
• bits_per_sample int16_t : The number of bits per sample.
• buffer_size_secs int32_t : The size in seconds of the internal buffer used to buffer PCM data i.e. internal circular buffer will be of size sample_rate * buffer_size_secs.
• device_index int32_t : The index of the audio device to use. A value of (-1) will resort to default device.
• object pv_speaker_t * * : PvSpeaker object to be initialized.

Returns

• pv_speaker_status_t : Returned status code.

pv_speaker_delete()

pv_speaker_status_t pv_speaker_delete(pv_speaker_t *object);

Releases resources acquired by PvSpeaker.

Parameters

• object pv_speaker_t * : PvSpeaker object.

pv_speaker_start()

pv_speaker_status_t pv_speaker_start(pv_speaker_t *object);

Starts the audio output device. After starting, PCM data can be sent to the audio output device via pv_speaker_write() and/or pv_speaker_flush().

Parameters

• object pv_speaker_t * : PvSpeaker object.

Returns

• pv_speaker_status_t : Returned status code.

pv_speaker_stop()

pv_speaker_status_t pv_speaker_stop(pv_speaker_t *object);

Stops the audio output device.

Parameters

• object pv_speaker_t * : PvSpeaker object.

Returns

• pv_speaker_status_t : Returned status code.

pv_speaker_write()

pv_speaker_status_t pv_speaker_write(
        pv_speaker_t *object,
        int8_t *pcm,
        int32_t pcm_length,
        int32_t *written_length);

Synchronous call to write PCM data to the internal circular buffer for audio playback. Only writes as much PCM data as the internal circular buffer can currently fit.

Parameters

• object pv_speaker_t * : PvSpeaker object.
• pcm int8_t * : Pointer to the PCM data that will be written.
• pcm_length int32_t * : Number of samples in the PCM data.
• written_length int32_t * : Number of samples that were successfully written. This value may be less than or equal to pcm_length, depending on the current state of the internal circular buffer.

Returns

• pv_speaker_status_t : Returned status code.

pv_speaker_flush()

pv_speaker_status_t pv_speaker_flush(
        pv_speaker_t *object,
        int8_t *pcm,
        int32_t pcm_length,
        int32_t *written_length);

Synchronous call to write PCM data to the internal circular buffer for audio playback. This blocks the thread until all PCM data (including PCM data written in previous calls to pv_speaker_write()) have been successfully written and played.

To simply wait for PCM data written in previous calls to finish playing, call pv_speaker_flush() with pcm set to NULL and pcm_length set to 0.

Parameters

• object pv_speaker_t * : PvSpeaker object.
• pcm int8_t * : Pointer to the PCM data that will be written.
• pcm_length int32_t * : Number of samples in the PCM data.
• written_length int32_t * : Number of samples that were successfully written. This value should always match pcm_length, unless an error occurred.

Returns

• pv_speaker_status_t : Returned status code.

pv_speaker_write_to_file()

pv_speaker_status_t pv_speaker_write_to_file(
        pv_speaker_t *object,
        const char *output_wav_path);

Writes PCM data passed to PvSpeaker to a specified WAV file. The file will be ready after pv_speaker_stop() or pv_speaker_delete() has been called.

Parameters

• object pv_speaker_t * : PvSpeaker object.
• output_wav_path const char * : Path to the output WAV file where the PCM data will be written.

Returns

• pv_speaker_status_t : Returned status code.

pv_speaker_get_is_started()

bool pv_speaker_get_is_started(pv_speaker_t *object);

Gets whether the given instance of pv_speaker_t has started and is available to receive PCM data.

Parameters

• object pv_speaker_t * : PvSpeaker object.

Returns

• bool : A boolean indicating whether PvSpeaker has started and is available to receive PCM data.

pv_speaker_get_selected_device()

const char *pv_speaker_get_selected_device(pv_speaker_t *object);

Gets the audio device that the given pv_speaker_t instance is using.

Parameters

• object pv_speaker_t * : PvSpeaker object.

Returns

• const char * : A string containing the name of the device.

pv_speaker_get_available_devices()

pv_speaker_status_t pv_speaker_get_available_devices(
        int32_t *device_list_length,
        char ***device_list);

Gets the list of available audio devices that can be used for playing audio. Free the returned device_list array using pv_speaker_free_available_devices().

Parameters

• device_list_length int32_t * : The number of available audio devices.
• device_list char * * * : The output array containing the list of available audio devices.

Returns

• pv_speaker_status_t : Returned status code.

pv_speaker_free_available_devices()

void pv_speaker_free_available_devices(
        int32_t device_list_length,
        char **device_list);

Frees the device list initialized by pv_speaker_get_available_devices().

Parameters

• device_list_length int32_t : The number of audio devices.
• device_list char * * : The array containing the list of audio devices.

pv_speaker_status_to_string()

const char *pv_speaker_status_to_string(pv_speaker_status_t status);

Provides string representations of the given status code.

Parameters

• status pv_speaker_status_t : Status code.

Returns

• const char * : String representation of the status code.

pv_speaker_version()

const char *pv_speaker_version(void);

Getter for the PvSpeaker version.

Returns

• const char * : Version string.

pv_speaker_status_t

typedef enum {
    PV_SPEAKER_STATUS_SUCCESS = 0,
    PV_SPEAKER_STATUS_OUT_OF_MEMORY,
    PV_SPEAKER_STATUS_INVALID_ARGUMENT,
    PV_SPEAKER_STATUS_INVALID_STATE,
    PV_SPEAKER_STATUS_BACKEND_ERROR,
    PV_SPEAKER_STATUS_DEVICE_ALREADY_INITIALIZED,
    PV_SPEAKER_STATUS_DEVICE_NOT_INITIALIZED,
    PV_SPEAKER_STATUS_IO_ERROR,
    PV_SPEAKER_STATUS_RUNTIME_ERROR
} pv_speaker_status_t;

Status code enum.