PyAudio

Warnings

• gotcha PyAudio requires the PortAudio system library (specifically, its development headers) to be installed before `pip install pyaudio` can succeed. This is a common installation barrier.
  Fix: On Debian/Ubuntu: `sudo apt-get install portaudio19-dev`. On macOS: `brew install portaudio`. On Windows, pre-compiled wheels are often available, but if not, manual compilation or using specific build tools might be necessary.
• gotcha Forgetting to close streams (`stream.close()`) and terminate the PyAudio instance (`p.terminate()`) can lead to resource leaks, prevent other applications from accessing audio devices, or cause unexpected behavior.
  Fix: Always ensure `stream.close()` is called on all open streams and `p.terminate()` is called once when you are finished using PyAudio, typically at the end of your script or in a `finally` block.
• gotcha Encountering `IndexError: no input device found` or `OSError: [Errno -9996] Invalid output device` indicates issues with audio device detection, permissions, or drivers. This is common on fresh installs or virtual machines.
  Fix: Verify that your audio hardware is correctly configured and drivers are installed. Check system audio input/output settings and permissions for your application. You might need to specify a device index manually using `p.get_device_info_by_index()`.
• gotcha The `stream.write()` and `stream.read()` methods expect audio data as raw `bytes`. Passing data in other formats (e.g., `str`, `list`, `numpy.ndarray` without conversion) will result in `TypeError` or `ValueError`.
  Fix: Always ensure your audio data is converted to `bytes` in the correct format (e.g., `paInt16` for 16-bit signed integers) and byte order before passing it to `stream.write()`. Similarly, `stream.read()` returns `bytes` that need to be parsed.

Install

• pip install pyaudio Basic Installation (requires system PortAudio)
• sudo apt-get install portaudio19-dev # Debian/Ubuntu brew install portaudio # macOS Install PortAudio development headers

Imports

• PyAudio

  import pyaudio
  p = pyaudio.PyAudio()

• Stream

  import pyaudio
  p = pyaudio.PyAudio()
  stream = p.open(...)

Quickstart

This quickstart demonstrates how to initialize PyAudio, generate a simple sine wave, and play it back through your default audio output device. It showcases stream creation, data writing, and proper resource cleanup.

import pyaudio
import math

# Configuration
CHUNK = 1024
FORMAT = pyaudio.paInt16
CHANNELS = 1
RATE = 44100
FREQUENCY = 440  # A4 note
DURATION = 3     # seconds

# Initialize PyAudio
p = pyaudio.PyAudio()

# Generate a sine wave
def generate_sine_wave(frequency, duration, rate, amplitude=1.0):
    samples = []
    for i in range(int(rate * duration)):
        value = amplitude * math.sin(2 * math.pi * frequency * (i / rate))
        # Scale to 16-bit integer range
        samples.append(int(value * 32767))
    # Convert to bytes (little-endian, signed)
    return b''.join(s.to_bytes(2, byteorder='little', signed=True) for s in samples)

print(f"Generating a {FREQUENCY} Hz sine wave for {DURATION} seconds...")
wave_data = generate_sine_wave(FREQUENCY, DURATION, RATE)

# Open stream for playback
stream = p.open(format=FORMAT,
                channels=CHANNELS,
                rate=RATE,
                output=True)

print("Playing audio...")
stream.write(wave_data)
print("Finished playing.")

# Clean up
stream.stop_stream()
stream.close()
p.terminate()