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 XP/2000 (native and cygwin), and Apple Mac OS X 10.4+—but it could use more testing.

PyAudio is inspired by:

pyPortAudio/fastaudio: Python bindings for PortAudio v18 API.
tkSnack: cross-platform sound toolkit for Tcl/Tk and Python.

What's new

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.0, with your choice of: Binaries, Ubuntu/Debian packages, or Sources.

Binaries

Microsoft Windows

Includes: PortAudio v19 [SVN r1368—March 3, 2008]

Requirements:

Microsoft Windows XP/2000
Python 2.4.4 or Python 2.5.2

Download:		PyAudio for Python 2.4.4 `md5sum: ac3449259ef174addc8cb4f67040cec3`
		PyAudio for Python 2.5.2 `md5sum: f0c2b42d758491b59bc1df44c366b36e`

Apple Mac OS X (Universal)

Includes: PortAudio v19 [SVN r1368—March 3, 2008]

Requirements:

Apple Mac OS X 10.4 or 10.5
With Mac OS X 10.4, you will need to install MacPython 2.5.2
(or MacPython 2.4.4 if preferred).

Download: PyAudio for Mac OS X (Universal)
md5sum: 13b22f58e8aa8817ba0306c5a744a57f

Packages

Debian/Ubuntu 7.10

To install, download the package (python-pyaudio_0.2.0_i386.deb) and then run:


% apt-get install libportaudio2 python-support

% dpkg -i python-pyaudio_0.2.0_i386.deb

Download: PyAudio deb package
md5sum: d0120d0c941c9a884e4430829f00def5

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: 646189ef5cf5d4bf60815b0a2d10fd2d

Subversion:


% svn co https://svn.csail.mit.edu/pyaudio/trunk/pyaudio/ pyaudio-0.2.0

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)

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,

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.

Special thanks to Justin Mazzola Paluska for packaging PyAudio 0.2.0 for Debian/Ubuntu!

Contact

Comments and suggestions welcomed. Send mail to my first name at mit.edu.