Audio Output
C Quick Start

Platforms

• Linux (x86_64)
• macOS (x86_64, arm64)
• Windows (x86_64, arm64)
• Raspberry Pi (3, 4, 5)

Requirements

• CMake 3.10+.
• C99 compatible compiler.
• Windows: MinGW.

Quick Start

Setup

Include the public header files (pv_speaker.h and pv_circular_buffer.h).

Usage

1. Create a PvSpeaker object:

#include "pv_speaker.h"

const int32_t sample_rate = 22050;
const int16_t bits_per_sample = 16;
const int32_t buffer_size_secs = 20;
const int32_t device_index = -1; // -1 == default device

pv_speaker_t *speaker = NULL;
pv_speaker_status_t status = pv_speaker_init(
        sample_rate,
        bits_per_sample,
        buffer_size_secs,
        device_index,
        &speaker);
if (status != PV_SPEAKER_STATUS_SUCCESS) {
    // handle PvSpeaker init error
}

2. Start the audio output device:

pv_speaker_status_t status = pv_speaker_start(speaker);
if (status != PV_SPEAKER_STATUS_SUCCESS) {
    // handle PvSpeaker start error
}

3. Write PCM data to the speaker:

int32_t num_samples;
int8_t *pcm = get_pcm_data(&num_samples);
int32_t written_length = 0;

pv_speaker_status_t status = pv_speaker_write(speaker, pcm, num_samples, &written_length);
if (status != PV_SPEAKER_STATUS_SUCCESS) {
    // handle PvSpeaker write error
}

Note: the pv_speaker_write() method only writes as much PCM data as the internal circular buffer can currently fit, and returns the number of samples that were successfully written via written_length.

4. When all frames have been written, call pv_speaker_flush() to wait for all buffered PCM (i.e. previously buffered via pv_speaker_write()) to be played:

int32_t num_samples;
int8_t *pcm = NULL;
int32_t written_length = 0;

pv_speaker_status_t status = pv_speaker_flush(speaker, pcm, num_samples, &written_length);
if (status != PV_SPEAKER_STATUS_SUCCESS) {
    // handle PvSpeaker flush error
}

Note: calling pv_speaker_flush() with a pcm pointer to actual PCM data (and corresponding num_samples) will both write that PCM data and wait for all buffered PCM data to finish.

5. Stop the audio output device:

pv_speaker_status_t status = pv_speaker_stop(speaker);
if (status != PV_SPEAKER_STATUS_SUCCESS) {
    // handle PvSpeaker stop error
}

6. Release resources used by PvSpeaker:

pv_speaker_delete(speaker);

Selecting an Audio Device

To print a list of available audio devices:

char **device_list = NULL;
int32_t device_list_length = 0;

pv_speaker_status_t status = pv_speaker_get_available_devices(
        &device_list_length,
        &device_list);
if (status != PV_SPEAKER_STATUS_SUCCESS) {
    // handle PvSpeaker get audio devices error
}

fprintf(stdout, "Printing devices...\n");
for (int32_t i = 0; i < device_list_length; i++) {
    fprintf(stdout, "index: %d, name: %s\n", i, device_list[i]);
}

pv_speaker_free_available_devices(device_list_length, device_list);

The index of the device in the returned list can be used in pv_speaker_init() to select that device for playing.

Demo

For the PvSpeaker C SDK, we offer a demo application that demonstrates how to use PvSpeaker to play audio from an audio file (.wav).

Setup

1. Clone the repository:

git clone --recurse-submodules https://github.com/Picovoice/pvspeaker.git

2. Build the project:

cd demo/c
cmake -S . -B build -DPV_SPEAKER_PLATFORM={PV_SPEAKER_PLATFORM}
cmake --build build

The {PV_SPEAKER_PLATFORM} variable will set the compilation flags for the given platform. Exclude this variable to get a list of possible values.

Usage

To see the usage options for the demo:

./pv_speaker_demo

Get a list of available audio playback devices:

./pv_speaker_demo --show_audio_devices

Play a file with a given audio device index:

./pv_speaker_demo -i test.wav -d 2

Hit Ctrl+C if you wish to stop playing audio before it completes. If no audio device index (-d) is provided, the demo will use the system's default audio player device.

For more information about our PvSpeaker demo, head over to our GitHub repository.

Resources