Audio Output
Python Quick Start

Platforms

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

Requirements

• Python 3.8+
• PIP

Quick Start

Setup

1. Install Python 3.

2. Install the pvspeaker Python package using PIP:

pip3 install pvspeaker

Usage

Initialize and start PvSpeaker:

from pvspeaker import PvSpeaker

speaker = PvSpeaker(sample_rate=22050, bits_per_sample=16)

speaker.start()

Write PCM data to the speaker:

def get_next_audio_frame():
    pass

written_length = speaker.write(get_next_audio_frame())

Note: the 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.

When all frames have been written, run flush() to wait for all buffered pcm data (i.e. previously buffered via write()) to be played:

speaker.flush()

Note: calling flush() with PCM data as an argument will both write that PCM data and wait for all buffered PCM data to finish.

def get_remaining_audio_frames():
    pass

speaker.flush(get_remaining_audio_frames())

To stop the audio output device, run stop():

speaker.stop()

Note that in order to stop the audio before it finishes playing, stop() must be run on a separate thread from flush().

Once you are done (i.e. no longer need PvSpeaker to write and/or play PCM), free the resources acquired by PvSpeaker by calling delete(). Be sure to first call stop() if the audio is still playing. Otherwise, if the audio has already finished playing, you do not have to call stop() before delete():

speaker.delete()

Selecting an Audio Device

To get a list of available audio devices:

devices = PvSpeaker.get_available_devices()

The index of the device in the returned list can be used in __init__() to select that device for audio output:

speaker = PvSpeaker(
    sample_rate=22050,
    bits_per_sample=16,
    device_index=2)

Demo

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

Setup

Install the pvspeakerdemo Python package using PIP:

pip3 install pvspeakerdemo

This package installs command-line utilities for the PvSpeaker Python demo.

Usage

Use the --help flag to see the usage options for the demo:

pv_speaker_demo --help

Run the following to see what devices are available for audio playback:

pv_speaker_demo --show_audio_devices

Run the demo with the desired audio device (or -1 for the default one) and an input file path:

pv_speaker_demo --audio_device_index ${DEVICE_INDEX} --input_wav_path ${INPUT_WAV_PATH}

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

Resources