Snakey: Headphones wearing Python

PyAudio

PyAudio provides Python bindings for PortAudio, the cross-platform audio I/O library. With PyAudio, you can easily use Python to play and record audio on a variety of platforms.

PyAudio is designed to work with the PortAudio v19 API 2.0. Note that PyAudio currently only supports blocking-mode audio I/O.

PyAudio is still super-duper alpha quality. It has run on GNU/Linux 2.6, Microsoft Windows 7/XP, and Apple Mac OS X 10.5+—but it could use more testing.

PyAudio is inspired by:

What's new

April 20, 2012

This web page has been translated to Russian—thanks to the efforts of Oleg Meister!

March 7, 2012

This web page has been translated to German—thanks to the efforts of Olga Babenko!

December 7, 2010

This web page has been translated to Belorussian—thanks to the efforts of Jason Fragoso!

November 2, 2010

PyAudio 0.2.4 has been uploaded to Debian (sid). A huge thanks to Felipe Sateler for sponsoring the package!

October 12, 2010

PyAudio 0.2.4 is a maintenance release—there are no new features or bug fixes. The binary packages now include PortAudio-v19 (r1535). The source for PyAudio is now in git (previously subversion).

November 2, 2008

PyAudio 0.2.3 fixes several outstanding bugs (thanks to all who have sent patches); see the CHANGELOG for details. PyAudio 0.2.3 provides bindings for PortAudio-v19 (r1395) and now includes binary distributions for Python 2.4, 2.5, and 2.6.

March 5, 2008

PyAudio 0.2.0 now works with both Python 2.4 and Python 2.5. Additionally, PyAudio features support for PortAudio's Mac OS X Host API Specific Stream Info extensions (e.g., for channel mapping)—see examples below. The new binary installers include an updated version of PortAudio-v19 (r1368).

Download

The current version is PyAudio v0.2.4, with your choice of: Binaries, Ubuntu/Debian packages, or Sources. You can also download previous versions of PyAudio.

Binaries

Microsoft Windows
Includes: PortAudio v19 [SVN r1535]
Requirements:
Download:   PyAudio for Python 2.7
md5sum: 03221f0e5a33009c4fae8d7fecf98ece
PyAudio for Python 2.6
md5sum: 9d56432e8e1cd1c72f562852160ac938
PyAudio for Python 2.5.2
md5sum: a5553f432c82b953012a83c8883c0a03
PyAudio for Python 2.4.4
md5sum: ab94d430a4ee23163373508d40b82af6
Notes:   To install Python for all users in Windows Vista, jaux.net offers some hints.

Apple Mac OS X (Universal)
Includes: PortAudio v19 [SVN r1535]
Requirements: Apple Mac OS X 10.5 or 10.6
Download:   PyAudio for Mac OS X (Universal)
md5sum: cb3da46863168fa6eec5ddcbf73a3815

Packages

Debian/Ubuntu
To install, download the package and then run:
% dpkg -i python-pyaudio_0.2.4-1_{i386,amd64}.deb

Download:   PyAudio deb package (i386)
md5sum: b0635f31c374b6c0e0e94fdec80e1e3b
PyAudio deb package (amd64)
md5sum: 3d7899a18ab2f90b3cc49cc19a0805c6

Source

PyAudio Source
To build PyAudio from source, you will also need to build PortAudio v19. See compilation hints for some instructions on building PyAudio for GNU/Linux, Microsoft Windows (cygwin and Win32), and Apple Mac OS X.
Download:   PyAudio tarball
md5sum: 623809778f3d70254a25492bae63b575

Git:

% git clone http://people.csail.mit.edu/hubert/git/pyaudio.git

Documentation

Getting started with PyAudio: by example.

Additionally, you can browse the PyAudio API documentation. PyAudio roughly mirrors the PortAudio v19 API 2.0.

If you're building PyAudio from source, here are compilation hints for building PyAudio on GNU/Linux, Windows (cygwin or Win32), and Mac OS X.

Examples

Note that the PyAudio source distribution contains a set of demo scripts. Here's a selection from that set:
""" Play a WAVE file. """

import pyaudio
import wave
import sys

chunk = 1024

if len(sys.argv) < 2:
    print "Plays a wave file.\n\n" +\
          "Usage: %s filename.wav" % sys.argv[0]
    sys.exit(-1)

wf = wave.open(sys.argv[1], 'rb')

p = pyaudio.PyAudio()

# open stream
stream = p.open(format =
                p.get_format_from_width(wf.getsampwidth()),
                channels = wf.getnchannels(),
                rate = wf.getframerate(),
                output = True)

# read data
data = wf.readframes(chunk)

# play stream
while data != '':
    stream.write(data)
    data = wf.readframes(chunk)

stream.close()
p.terminate()
""" Record a few seconds of audio and save to a WAVE file. """

import pyaudio
import wave
import sys

chunk = 1024
FORMAT = pyaudio.paInt16
CHANNELS = 1
RATE = 44100
RECORD_SECONDS = 5
WAVE_OUTPUT_FILENAME = "output.wav"

p = pyaudio.PyAudio()

stream = p.open(format = FORMAT,
                channels = CHANNELS,
                rate = RATE,
                input = True,
                frames_per_buffer = chunk)

print "* recording"
all = []
for i in range(0, RATE / chunk * RECORD_SECONDS):
    data = stream.read(chunk)
    all.append(data)
print "* done recording"

stream.close()
p.terminate()

# write data to WAVE file
data = ''.join(all)
wf = wave.open(WAVE_OUTPUT_FILENAME, 'wb')
wf.setnchannels(CHANNELS)
wf.setsampwidth(p.get_sample_size(FORMAT))
wf.setframerate(RATE)
wf.writeframes(data)
wf.close()
""" A wire between input and output. """

import pyaudio
import sys

chunk = 1024
FORMAT = pyaudio.paInt16
CHANNELS = 1
RATE = 44100
RECORD_SECONDS = 5

p = pyaudio.PyAudio()

stream = p.open(format = FORMAT,
                channels = CHANNELS,
                rate = RATE,
                input = True,
                output = True,
                frames_per_buffer = chunk)

print "* recording"
for i in range(0, 44100 / chunk * RECORD_SECONDS):
    data = stream.read(chunk)
    stream.write(data, chunk)
print "* done"

stream.stop_stream()
stream.close()
p.terminate()
""" Mac OS X only: specifying channel maps. """

import pyaudio
import wave
import sys

chunk = 1024

PyAudio = pyaudio.PyAudio

if len(sys.argv) < 2:
    print "Plays a wave file.\n\nUsage: %s filename.wav" % sys.argv[0]
    sys.exit(-1)

wf = wave.open(sys.argv[1], 'rb')

p = PyAudio()

# standard L-R stereo
# channel_map = (0, 1)

# reverse: R-L stereo
# channel_map = (1, 0)

# no audio
# channel_map = (-1, -1)

# left channel audio --> left speaker; no right channel
# channel_map = (0, -1)

# right channel audio --> right speaker; no left channel
# channel_map = (-1, 1)

# left channel audio --> right speaker
# channel_map = (-1, 0)

# right channel audio --> left speaker
channel_map = (1, -1)
# etc...

try:
    stream_info = pyaudio.PaMacCoreStreamInfo(
        # default:
        flags = pyaudio.PaMacCoreStreamInfo.paMacCorePlayNice,
        channel_map = channel_map)
except AttributeError:
    print "Sorry, couldn't find PaMacCoreStreamInfo. Make sure that" \
          " you're running on Mac OS X."
    import sys
    sys.exit(-1)

print "Stream Info Flags:", stream_info.get_flags()
print "Stream Info Channel Map:", stream_info.get_channel_map()

# open stream
stream = p.open(format =
                p.get_format_from_width(wf.getsampwidth()),
                channels = wf.getnchannels(),
                rate = wf.getframerate(),
                output = True,
                output_host_api_specific_stream_info = stream_info)

# read data
data = wf.readframes(chunk)

# play stream
while data != '':
    stream.write(data)
    data = wf.readframes(chunk)

stream.stop_stream()
stream.close()

p.terminate()

License

PyAudio is distributed under the MIT License. That is to say,

Copyright (c) 2006-2010 Hubert Pham

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements

The development of PyAudio was funded in part by the Cambridge-MIT Institute and T-Party.

Many thanks to Andrew Baldwin, Alex ThreeD, Timothée Lecomte, Frank Samuelson, Matthieu Brucher, and Chris Stawarz for their much appreciated suggestions and patches—as well as to others who have written to say hello!

Also special thanks to Justin Mazzola Paluska and Felipe Sateler for Debian/Ubuntu packaging help.

Translations

Contact

Comments and suggestions welcomed. Send mail to my first name at mit.edu.
h-u-b-e-r-t