How to Play Audio in Python: PCM Audio Playback Guide

Capturing and playing real-time PCM audio in Python is a core requirement for text-to-speech, voice assistants, and other voice AI applications. While general-purpose audio libraries such as PyAudio or sounddevice can be used for audio playback, they are not specifically designed for real-time speech and voice-driven workloads. PvSpeaker is a cross-platform Python audio playback library that streams raw PCM audio directly to the system audio output on Windows, macOS, Linux, and Raspberry Pi, with a focus on real-time speech playback. This tutorial shows how to set up PvSpeaker and stream PCM audio in Python for voice AI applications.

Quick Answer: How to Play Audio in Python

PvSpeaker is designed specifically to stream audio from speech or voice applications. Install the pvspeaker package on PyPI using pip, initialize PvSpeaker with your audio format (sample rate and bit depth), call start() to start the audio output device, write() to stream PCM data to the speaker, flush() to ensure all audio finishes playing, then stop() and delete() to clean up resources.

What you'll learn in this guide:

• Install & set up PvSpeaker for audio playback (runs on: Windows, macOS, Linux, Raspberry Pi)
• Select specific audio output devices for multi-speaker systems
• Stream PCM audio data to speakers in real-time
• Play audio files and handle audio buffers

Python Audio Playback: Requirements and Platform Support

System Requirements for Python Audio Output

• Python 3.9+
• PIP package manager

Python Audio Playback Platform Compatibility

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

Play Audio in Python: Step-by-Step Guide

Step 1: Install PvSpeaker Python Package for Audio Playback

Install the PvSpeaker Python package using pip:

pip3 install pvspeaker

This lightweight SDK provides cross-platform audio playback without requiring platform-specific dependencies or complex audio library configuration.

Step 2: Initialize PvSpeaker with Audio Format Specifications

Import PvSpeaker and create an instance configured with your audio format:

from pvspeaker import PvSpeaker

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

The sample rate and bit depth must match your audio source format.

Step 3: Start the Audio Output Device

Call start() to initialize the audio output device and prepare it for streaming PCM data:

speaker.start()

Starting the speaker allocates audio hardware resources and creates an internal buffer for smooth playback. Once started, you can begin writing PCM audio frames.

Step 4: Stream PCM Audio Data to the Speaker

Use the write() method to send PCM audio frames to the speaker for playback:

import time

def get_next_audio_frame():
    # Return PCM audio data from your source
    # (e.g., text-to-speech engine, audio file, etc.)
    pass

total_written = 0
pcm = get_next_audio_frame()

while total_written < len(pcm):
    written = speaker.write(pcm[total_written:])
    total_written += written

    # Wait some time before attempting to re-write if the buffer is full
    if total_written < len(pcm):
        time.sleep(1)

The write() method fills PvSpeaker's internal circular buffer with as much data as it can hold and returns the number of samples successfully written. To ensure all audio is played, we need to track the number of samples written and retry sending any remaining data until the full frame is streamed.

Configure the Capacity of Internally Buffered Audio

By default, PvSpeaker buffers up to 20 seconds of audio. To adjust the size of the internal circular buffer, use buffer_size_secs when initializing:

speaker = PvSpeaker(
    sample_rate=sample_rate,
    bits_per_sample=bits_per_sample,
    buffer_size_secs=30 # to hold up to 30 seconds of audio
)

Step 5: Flush Buffered Audio to Complete Playback

When all audio data has been written, call flush() to wait for all buffered PCM data to finish playing:

speaker.flush()

The flush() method blocks until all previously buffered audio has been played through the speakers. This ensures audio isn't cut off prematurely when your program exits.

Step 6: Stop Playback and Release Audio Resources

When finished with audio playback, stop the speaker and free allocated resources:

speaker.stop()
speaker.delete()

Call stop() to halt audio output if playback is still in progress. Note that to stop audio before it finishes playing, stop() must be called from a separate thread from flush().

Always call delete() to release audio hardware resources when you're completely done with the speaker. If audio has already finished playing after flush(), you can call delete() directly without stop().

Selecting a Specific Audio Output Device

For systems with multiple audio output devices (like external speakers, headphones, or HDMI audio), you can select a specific device by index.

First, get a list of available audio output devices:

devices = PvSpeaker.get_available_devices()
for index, device in enumerate(devices):
    print(f"{index}: {device}")

Then specify the desired device when initializing PvSpeaker:

speaker = PvSpeaker(
    sample_rate=22050,
    bits_per_sample=16,
    device_index=2  # use the device at index 2 in the list
)

If you don't specify a device_index, PvSpeaker uses the system's default audio output device.

Complete Python Audio Playback Example

This example shows how to play a WAV file using PvSpeaker by converting it into raw PCM samples and streaming them incrementally to the audio output device.

The wave module is used to open and validate the WAV file, extract its format (sample rate, bit depth, and channel count), and convert the audio to PCM data.

To mimic real-time audio generation, the PCM data is written to the speaker in one-second chunks rather than all at once. Each chunk is fully written using a loop that accounts for partial writes, which can occur depending on the underlying audio buffer state.

Before running the example code, replace ${AUDIO_FILE_PATH} with the path to the WAV file you want to play.

import wave
import array
import threading
import time
from pvspeaker import PvSpeaker


def worker_function(speaker, completion_event):
    """Run flush() in a separate thread to allow interruption."""
    speaker.flush()
    completion_event.set()


def play_wav_file(wav_path):
    """Play a WAV file using PvSpeaker with proper error handling."""
    
    wavfile = None
    speaker = None
    
    try:
        # Open and validate WAV file
        wavfile = wave.open(wav_path, "rb")
        
        sample_rate = wavfile.getframerate()
        bits_per_sample = wavfile.getsampwidth() * 8
        num_channels = wavfile.getnchannels()
        num_samples = wavfile.getnframes()
        
        # Validate audio format
        if bits_per_sample not in [8, 16, 24, 32]:
            raise ValueError(f"Unsupported bits per sample: {bits_per_sample}")
        
        if num_channels != 1:
            raise ValueError("WAV file must be mono (single channel)")
        
        # Initialize speaker with WAV file format
        speaker = PvSpeaker(
            sample_rate=sample_rate,
            bits_per_sample=bits_per_sample
        )
        
        print(f"PvSpeaker version: {speaker.version}")
        print(f"Using device: {speaker.selected_device}")
        
        # Read WAV file data
        wav_bytes = wavfile.readframes(num_samples)
        
        # Convert to appropriate PCM format based on bit depth
        pcm = None
        if bits_per_sample == 8:
            pcm = list(array.array('B', wav_bytes))
        elif bits_per_sample == 16:
            pcm = list(array.array('h', wav_bytes))
        elif bits_per_sample == 24:
            pcm = []
            for i in range(0, len(wav_bytes), 3):
                sample = int.from_bytes(wav_bytes[i:i + 3], byteorder='little', signed=True)
                pcm.append(sample)
        elif bits_per_sample == 32:
            pcm = list(array.array('i', wav_bytes))
        
        # Start output audio device
        speaker.start()
        
        print("Playing audio...")
        
        # Write PCM data in chunks (one second at a time)
        chunk_size = sample_rate
        for i in range(0, len(pcm), chunk_size):
            chunk = pcm[i:i + chunk_size]
            total_written = 0
            
            # Ensure entire chunk is written
            while total_written < len(chunk):
                written = speaker.write(chunk[total_written:])
                total_written += written
                
                if total_written < len(chunk):
                    time.sleep(0.1)
        
        print("Waiting for audio to finish...")
        
        # Run flush() in a separate thread to allow interruption via stop()
        completion_event = threading.Event()
        worker_thread = threading.Thread(
            target=worker_function, 
            args=(speaker, completion_event)
        )
        worker_thread.start()
        completion_event.wait()
        worker_thread.join()
        
        speaker.stop()
        print("Finished playing audio")
        
    except KeyboardInterrupt:
        print("\nStopped by user")
        if speaker is not None:
            speaker.stop()
    finally:
        # Always clean up resources
        if speaker is not None:
            speaker.delete()
        if wavfile is not None:
            wavfile.close()


# Example usage
if __name__ == "__main__":
    play_wav_file("${AUDIO_FILE_PATH}")

Overall, this example covers the full audio playback workflow: loading and validating an audio file, converting it to PCM samples, streaming audio in controlled chunks, waiting for playback to finish, and shutting down the audio device.

For a more complete demo application, refer to the PvSpeaker Python demo on GitHub. For more complete implementation details, refer to the PvSpeaker Python API documentation.

Bonus: to see how PvSpeaker can be integrated in a real-time speech audio generation & playback pipeline, check out the Orca Streaming Text-to-Speech Python Demo on GitHub.

Format Specifications for Audio Playback

PvSpeaker supports the following PCM audio formats:

• Sample Rates: Configurable (common: 16 kHz, 22.05 kHz, 44.1 kHz, 48 kHz)
• Bit Depth: 8-bit unsigned integer, or 16/24/32-bit signed integer
• Channels: Mono (single channel)
• Format: Raw PCM audio data

Ensure your audio source format matches the sample rate, bit depth, and number of channels specified when initializing PvSpeaker to avoid playback issues.

Next Steps: Build Voice AI Applications with Audio Playback

Now that you can play audio in Python, you can build complete voice AI applications:

• Python Text-to-Speech: Generate natural-sounding speech from text using Orca Streaming Text-to-Speech and play it with PvSpeaker.
• Voice Assistant in Python: Build offline voice assistants that listen, process, and respond with synthesized speech.

PvSpeaker integrates seamlessly with Picovoice's voice AI SDKs, enabling fully offline speech synthesis and playback without cloud dependencies.

Frequently Asked Questions