{"id":5014,"library":"pyaudio","title":"PyAudio","description":"PyAudio provides Python bindings for PortAudio, a cross-platform audio I/O library. It allows you to easily use Python to play and record audio on a variety of platforms. The current version is 0.2.14, and the library maintains a stable but slow release cadence.","status":"active","version":"0.2.14","language":"en","source_language":"en","source_url":"https://github.com/PyAudio/PyAudio","tags":["audio","sound","portaudio","io","multimedia"],"install":[{"cmd":"pip install pyaudio","lang":"bash","label":"Basic Installation (requires system PortAudio)"},{"cmd":"sudo apt-get install portaudio19-dev  # Debian/Ubuntu\nbrew install portaudio            # macOS","lang":"bash","label":"Install PortAudio development headers"}],"dependencies":[],"imports":[{"symbol":"PyAudio","correct":"import pyaudio\np = pyaudio.PyAudio()"},{"symbol":"Stream","correct":"import pyaudio\np = pyaudio.PyAudio()\nstream = p.open(...)"}],"quickstart":{"code":"import pyaudio\nimport math\n\n# Configuration\nCHUNK = 1024\nFORMAT = pyaudio.paInt16\nCHANNELS = 1\nRATE = 44100\nFREQUENCY = 440  # A4 note\nDURATION = 3     # seconds\n\n# Initialize PyAudio\np = pyaudio.PyAudio()\n\n# Generate a sine wave\ndef generate_sine_wave(frequency, duration, rate, amplitude=1.0):\n    samples = []\n    for i in range(int(rate * duration)):\n        value = amplitude * math.sin(2 * math.pi * frequency * (i / rate))\n        # Scale to 16-bit integer range\n        samples.append(int(value * 32767))\n    # Convert to bytes (little-endian, signed)\n    return b''.join(s.to_bytes(2, byteorder='little', signed=True) for s in samples)\n\nprint(f\"Generating a {FREQUENCY} Hz sine wave for {DURATION} seconds...\")\nwave_data = generate_sine_wave(FREQUENCY, DURATION, RATE)\n\n# Open stream for playback\nstream = p.open(format=FORMAT,\n                channels=CHANNELS,\n                rate=RATE,\n                output=True)\n\nprint(\"Playing audio...\")\nstream.write(wave_data)\nprint(\"Finished playing.\")\n\n# Clean up\nstream.stop_stream()\nstream.close()\np.terminate()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}