for
PortAudio
v19, the
cross-platform audio I/O library. With PyAudio, you can
easily use Python to play and record audio on a variety of
platforms, such as GNU/Linux, Microsoft Windows, and Apple
macOS.
PyAudio is distributed under the MIT License.
This library was originally inspired by:
pyPortAudio/fastaudio:
Python bindings for PortAudio
v18
API.
tkSnack
:
cross-platform sound toolkit for Tcl/Tk and Python.
What's new
December 26, 2022
PyAudio 0.2.13 is a new release focused on refactoring, maintenance, and
cleanup. See the CHANGELOG in the
source
distribution
for details. Notable changes include:
Fixed installation on Apple silicon. Thanks to Michael Parque for help
with updating and testing!
pyaudio.Stream
is
now
pyaudio.PyAudio.Stream
, which should not affect
existing code, as directly accessing the
module-level
pyaudio.Stream
class has always been
unsupported. Use
PyAudio.open
instead.
PaMacCoreStreamInfo.get_channel_map()
and
PaMacCoreStreamInfo.get_flags()
methods are
deprecated. Use the
channel_map
and
flags
properties, respectively, instead.
October 25, 2022
PyAudio 0.2.12 pre-compiled wheels for Microsoft Windows (32-bit and
64-bit) are now available for
Python 3.11
on
PyPI
.
Install using pip, as described
below
.
July 18, 2022
PyAudio 0.2.12 is a new release with many updates. See the CHANGELOG in
the
source distribution
for details. Notably, the
PyAudio build process for Microsoft Windows is streamlined, using the
native toolchain.
Special thanks to:
Sean Zimmermann for help with modernizing the Microsoft Windows
build process
Jason Hihn for suggesting the use paFramesPerBufferUnspecified as
the default frames per buffer
Eiichi Takamori for the patch that uses the system's preferred
encoding
Matěj Cepl for the patches that skip unit tests that require audio
hardware
Vasily Zakharov for fixes and suggestions to the documentation
Artur Janowiec for fixes to the website documentation
March 18, 2017
PyAudio 0.2.11 is a
new release with a bug fix related to memory management.
Many thanks to both Blaise Potard and Matthias Schaff for
discovering the issue and for their patches! Thanks as well to
Timothy Port for helping to correct a docstring.
January 16, 2017
PyAudio 0.2.10 is a new release with bug fixes related to
the Python GIL. It also introduces a few automated unit tests.
Great thanks to Michael Graczyk for discovering the GIL-related issues
and for submitting a patch!
October 19, 2015
PyAudio
installation
is better streamlined.
Install PyAudio on most platforms using pip.
October 18, 2015
PyAudio 0.2.9 is a new release with bug fixes related
to overflow error handling and IOError exception arguments.
Many thanks to Tony Jacobson for discovering and helping with
the overflow error. Thanks also to Sami Liedes for reporting
the IOError exception issue!
April 12, 2014
PyAudio 0.2.8 is a
new release with bug fixes related to the Python GIL and device name
encoding.
Many thanks to Jason Roehm for discovering and patching the
threading-related issue!
January 30, 2014
Many thanks to
Sebastian Audet, who
wrote
instructions
for building
PyAudio using Microsoft Visual Studio!
October 27, 2012
PyAudio 0.2.7 is a new release with:
Modernized documentation format
Fix for callback (non-blocking) operation
Binaries for Python 3.3
Thanks again to Bastian Bechtold for his help converting the
documentation for use with Sphinx! In addition, thanks to John
K. Luebs for the callback fix.
October 14, 2012
PyAudio 0.2.6 is a new release with:
Python 3
support
Callback (non-blocking) operation
Bug fixes
Many thanks to Bastian Bechtold and Bob Jamison for their
contributions! Without their patches and Bastian's careful
review, this release would still be far away. Also, great
thanks to Danilo J. S. Bellini for reporting bugs.
Note:
As of this update, PyAudio is
compatible with Python 2.6, Python 2.7, and Python 3.2. For
Python installations older than 2.6,
use
PyAudio 0.2.4
.
August 22, 2012
This web page has been
translated
to
French—thanks to the efforts of Cyril Danilevski!
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).
July 6, 2006
PyAudio 0.1.0 is released.
Older news...
Installation
The current version is
PyAudio v0.2.13
and supports
Python version 3.7+. Install PyAudio using pip on most platforms. For
PyAudio versions prior to v0.2.9, PyAudio distributed installation
binaries, which are
archived here
.
pip will fetch and install PyAudio wheels (prepackaged
binaries). Currently, there are wheels compatible with
official
distributions
for Python 3.7, 3.8, 3.9, 3.10, and 3.11.
Both 32-bit and 64-bit wheels are available.
These binaries include PortAudio v19 19.7.0, built using the
native compiler toolchain. They support the Windows MME API,
DirectSound, WASAPI, and WDM-KS. They do
not
include support for ASIO. If you require support for APIs not
included, you will need to compile PortAudio and PyAudio.
Homebrew and building PyAudio also require installing
the Command Line Tools for Xcode
(
more
information
).
pip will download the PyAudio source and build it for
your system. Be sure to install the portaudio library
development package (e.g.,
portaudio19-dev
) and
the python development package
(e.g.,
python3-all-dev
) beforehand.
For better isolation from system packages, consider
installing PyAudio in
a
virtualenv
.
To build PyAudio from source, you will also need to build
PortAudio
v19
. See the INSTALLATION file in the PyAudio source bundle for
build instructions.
if
len
(
sys
.
argv
)
<
2
:
print
(
f
'Plays a wave file. Usage:
{
sys
.
argv
[
0
]
}
filename.wav'
)
sys
.
exit
(
-
1
)
with
wave
.
open
(
sys
.
argv
[
1
],
'rb'
)
as
wf
:
# Instantiate PyAudio and initialize PortAudio system resources (1)
p
=
pyaudio
.
PyAudio
()
# Open stream (2)
stream
=
p
.
open
(
format
=
p
.
get_format_from_width
(
wf
.
getsampwidth
()),
channels
=
wf
.
getnchannels
(),
rate
=
wf
.
getframerate
(),
output
=
True
)
# Play samples from the wave file (3)
while
len
(
data
:=
wf
.
readframes
(
CHUNK
)):
# Requires Python 3.8+ for :=
stream
.
write
(
data
)
# Close stream (4)
stream
.
close
()
# Release PortAudio system resources (5)
p
.
terminate
()
"""PyAudio Example: Record a few seconds of audio and save to a wave file."""
import wave
import sys
import pyaudio
CHUNK = 1024
FORMAT = pyaudio.paInt16
CHANNELS = 1 if sys.platform == 'darwin' else 2
RATE = 44100
RECORD_SECONDS = 5
with wave.open('output.wav', 'wb') as wf:
p = pyaudio.PyAudio()
wf.setnchannels(CHANNELS)
wf.setsampwidth(p.get_sample_size(FORMAT))
wf.setframerate(RATE)
stream = p.open(format=FORMAT, channels=CHANNELS, rate=RATE, input=True)
print('Recording...')
for _ in range(0, RATE // CHUNK * RECORD_SECONDS):
wf.writeframes(stream.read(CHUNK))
print('Done')
stream.close()
p.terminate()
p = pyaudio.PyAudio()
stream = p.open(format=p.get_format_from_width(2),
channels=1 if sys.platform == 'darwin' else 2,
rate=RATE,
input=True,
output=True,
frames_per_buffer=CHUNK)
print('* recording')
for i in range(0, int(RATE / CHUNK * RECORD_SECONDS)):
stream.write(stream.read(CHUNK))
print('* done')
stream.close()
p.terminate()
if len(sys.argv) < 2:
print(f'Plays a wave file. Usage: {sys.argv[0]} filename.wav')
sys.exit(-1)
with wave.open(sys.argv[1], 'rb') as wf:
# Define callback for playback (1)
def callback(in_data, frame_count, time_info, status):
data = wf.readframes(frame_count)
# If len(data) is less than requested frame_count, PyAudio automatically
# assumes the stream is finished, and the stream stops.
return (data, pyaudio.paContinue)
# Instantiate PyAudio and initialize PortAudio system resources (2)
p = pyaudio.PyAudio()
# Open stream using callback (3)
stream = p.open(format=p.get_format_from_width(wf.getsampwidth()),
channels=wf.getnchannels(),
rate=wf.getframerate(),
output=True,
stream_callback=callback)
# Wait for stream to finish (4)
while stream.is_active():
time.sleep(0.1)
# Close the stream (5)
stream.close()
# Release PortAudio system resources (6)
p.terminate()
"""PyAudio Example: Audio wire between input and output. Callback version."""
import time
import sys
import pyaudio
DURATION = 5 # seconds
def callback(in_data, frame_count, time_info, status):
return (in_data, pyaudio.paContinue)
p = pyaudio.PyAudio()
stream = p.open(format=p.get_format_from_width(2),
channels=1 if sys.platform == 'darwin' else 2,
rate=44100,
input=True,
output=True,
stream_callback=callback)
start = time.time()
while stream.is_active() and (time.time() - start) < DURATION:
time.sleep(0.1)
stream.close()
p.terminate()
if len(sys.argv) < 2:
print(f'Plays a wave file. Usage: {sys.argv[0]} filename.wav')
sys.exit(-1)
# 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(
flags=pyaudio.PaMacCoreStreamInfo.paMacCorePlayNice,
channel_map=channel_map)
except AttributeError:
print(
'Could not find PaMacCoreStreamInfo. Ensure you are running on macOS.')
sys.exit(-1)
print('Stream Info Flags:', stream_info.flags)
print('Stream Info Channel Map:', stream_info.channel_map)
with wave.open(sys.argv[1], 'rb') as wf:
p = pyaudio.PyAudio()
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)
# Play stream
while len(data := wf.readframes(CHUNK)): # Requires Python 3.8+ for :=
stream.write(data)
stream.close()
p.terminate()
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.
Many thanks to Andrew Baldwin, Alex ThreeD, Timothée Lecomte,
Frank Samuelson, Matthieu Brucher, Chris Stawarz, Barry Walker, Bob
Jamison, Danilo J. S. Bellini, Bastian Bechtold, Christoph Gohlke,
Sebastian Audet, Jason Roehm, Tony Jacobson, Sami Liedes, Michael
Graczyk, Blaise Potard, Matthias Schaff, Timothy Port, Sean Zimmermann,
Jason Hihn, Eiichi Takamori, Matěj Cepl, Vasily Zakharov, and Artur
Janowiec for their much appreciated suggestions and patches—as
well as to others who have written to say hello!
Special thanks to Felipe Sateler and Justin Mazzola Paluska
for Debian/Ubuntu packaging help.
The development of PyAudio was funded in part by the
Cambridge-MIT Institute and T-Party.
Contact
For help with PyAudio, your best bet for a
timely response is to consult or post to
StackOverflow.
Comments, suggestions, and patches welcomed. Send mail to my first name