Skip to content

Python pyaudio Module: A Comprehensive Guide

The pyaudio module provides Python bindings for PortAudio, a cross-platform library for audio I/O. It allows you to work with audio data, including recording and playback of sound. This guide provides a detailed overview of the pyaudio module, including installation, basic usage, and examples.

Introduction to pyaudio

pyaudio is a Python library that provides an easy interface to PortAudio, allowing you to work with audio input and output. It supports a variety of audio formats and provides functions for recording and playing back audio data.

Installation

To use pyaudio, you need to install the module via pip.

Installing pyaudio

pip install pyaudio

If you encounter issues installing pyaudio, make sure you have the required development libraries installed. On some systems, you might need to install PortAudio separately.

  • Windows: You can download pre-built binaries from PyPI.
  • macOS: You can use Homebrew to install PortAudio:
brew install portaudio
  • Linux: Install PortAudio using your package manager. For example, on Ubuntu:
sudo apt-get install libportaudio2

Basic Usage

pyaudio provides interfaces for working with audio streams, including opening, recording, and playing audio.

Importing pyaudio

import pyaudio

Recording Audio

You can record audio by opening a stream with pyaudio and capturing audio data.

Basic Recording Example

import pyaudio
import wave

# Parameters for recording
FORMAT = pyaudio.paInt16  # Audio format (16-bit PCM)
CHANNELS = 1              # Number of audio channels (1 for mono, 2 for stereo)
RATE = 44100              # Sampling rate (samples per second)
CHUNK = 1024              # Chunk size (number of audio frames per buffer)
RECORD_SECONDS = 5        # Duration of recording (in seconds)
WAVE_OUTPUT_FILENAME = "output.wav"  # Output file name

audio = pyaudio.PyAudio()

# Open a new stream
stream = audio.open(format=FORMAT, channels=CHANNELS,
                    rate=RATE, input=True,
                    frames_per_buffer=CHUNK)

print("Recording...")

frames = []

# Record audio data
for i in range(0, int(RATE / CHUNK * RECORD_SECONDS)):
    data = stream.read(CHUNK)
    frames.append(data)

print("Recording finished.")

# Stop and close the stream
stream.stop_stream()
stream.close()
audio.terminate()

# Save the recorded audio data to a file
wave_file = wave.open(WAVE_OUTPUT_FILENAME, 'wb')
wave_file.setnchannels(CHANNELS)
wave_file.setsampwidth(audio.get_sample_size(FORMAT))
wave_file.setframerate(RATE)
wave_file.writeframes(b''.join(frames))
wave_file.close()

Playing Audio

You can play audio by opening a stream for output and writing audio data to it.

Basic Playback Example

import pyaudio
import wave

# Parameters for playback
CHUNK = 1024  # Chunk size

# Open the audio file
wf = wave.open('output.wav', 'rb')

audio = pyaudio.PyAudio()

# Open a new stream for playback
stream = audio.open(format=audio.get_format_from_width(wf.getsampwidth()),
                    channels=wf.getnchannels(),
                    rate=wf.getframerate(),
                    output=True)

print("Playing...")

# Read and play audio data
data = wf.readframes(CHUNK)
while data:
    stream.write(data)
    data = wf.readframes(CHUNK)

print("Playback finished.")

# Stop and close the stream
stream.stop_stream()
stream.close()
audio.terminate()

Streaming Audio

pyaudio also supports real-time audio streaming, allowing you to process and handle audio data on-the-fly.

Streaming Example

import pyaudio

# Parameters for streaming
FORMAT = pyaudio.paInt16
CHANNELS = 1
RATE = 44100
CHUNK = 1024

audio = pyaudio.PyAudio()

# Open a new stream for input and output
stream = audio.open(format=FORMAT, channels=CHANNELS,
                    rate=RATE, input=True, output=True,
                    frames_per_buffer=CHUNK)

print("Streaming...")

try:
    while True:
        data = stream.read(CHUNK)
        stream.write(data)
except KeyboardInterrupt:
    print("Streaming stopped.")

# Stop and close the stream
stream.stop_stream()
stream.close()
audio.terminate()

Error Handling

Handling errors is crucial for robust audio applications. Here’s how you can handle common errors:

Handling Errors

import pyaudio
import wave
import sys

try:
    audio = pyaudio.PyAudio()
    # Example: Open a stream (replace with your code)
    stream = audio.open(format=pyaudio.paInt16, channels=1, rate=44100, input=True)
    # More code here...
except Exception as e:
    print(f"An error occurred: {e}", file=sys.stderr)
finally:
    if 'stream' in locals() and stream.is_active():
        stream.stop_stream()
        stream.close()
    if 'audio' in locals():
        audio.terminate()

Conclusion

The pyaudio module provides a versatile and powerful way to work with audio in Python. With its support for recording, playing, and streaming audio, it is suitable for a variety of audio processing applications. By following the examples and guidelines provided in this report, you should be able to integrate pyaudio into your projects effectively.