Skip to main content

Play and Record Sound with Python

This Python module provides bindings for the PortAudio library and a few convenience functions to play and record NumPy arrays containing audio signals.

Documentation:

http://python-sounddevice.rtfd.org/

Code:

http://github.com/spatialaudio/python-sounddevice/

Python Package Index:

http://pypi.python.org/pypi/sounddevice/

Requirements

Python:

Of course, you’ll need Python. Any version where CFFI (see below) is supported should work. If you don’t have Python installed yet, you should get one of the distributions which already include CFFI and NumPy (and many other useful things), e.g. Anaconda or WinPython.

pip/setuptools:

Those are needed for the installation of the Python module and its dependencies. Most systems will have these installed already, but if not, you should install it with your package manager or you can download and install pip and setuptools as described on the pip installation page. If you happen to have pip but not setuptools, use this command:

pip install setuptools --user
CFFI:

The C Foreign Function Interface for Python is used to access the C-API of the PortAudio library from within Python. It supports CPython 2.6, 2.7, 3.x; and is distributed with PyPy 2.0 beta2 or later. You should install it with your package manager (if it’s not installed already), or you can get it with:

pip install cffi --user
PortAudio library:

The PortAudio library must be installed on your system (and CFFI must be able to find it). Again, you should use your package manager to install it. If you prefer, you can of course also download the sources and compile the library yourself. If you are using Mac OS X or Windows, the library will be installed automagically with pip (see “Installation” below).

NumPy (optional):

NumPy is only needed if you want to play back and record NumPy arrays. The classes sounddevice.RawStream, sounddevice.RawInputStream and sounddevice.RawOutputStream use plain Python buffer objects and don’t need NumPy at all. If you need NumPy, you should install it with your package manager or use a Python distribution that already includes NumPy (see above). Installing NumPy with pip is not recommended.

Installation

Once you have installed the above-mentioned dependencies, you can use pip to download and install the latest release with a single command:

pip install sounddevice --user

If you want to install it system-wide for all users (assuming you have the necessary rights), you can just drop the --user option.

To un-install, use:

pip uninstall sounddevice

Usage

First, import the module:

import sounddevice as sd

Playback

Assuming you have a NumPy array named myarray holding audio data with a sampling frequency of fs (in the most cases this will be 44100 or 48000 frames per second), you can play it back with sounddevice.play():

sd.play(myarray, fs)

This function returns immediately but continues playing the audio signal in the background. You can stop playback with sounddevice.stop():

sd.stop()

If you know that you will use the same sampling frequency for a while, you can set it as default using sounddevice.default.samplerate:

sd.default.samplerate = fs

After that, you can drop the samplerate argument:

sd.play(myarray)

Recording

To record audio data from your sound device into a NumPy array, use sounddevice.rec():

duration = 10  # seconds
myrecording = sd.rec(duration * fs, samplerate=fs, channels=2)

Again, for repeated use you can set defaults using sounddevice.default:

sd.default.samplerate = fs
sd.default.channels = 2

After that, you can drop the additional arguments:

myrecording = sd.rec(duration * fs)

This function also returns immediately but continues recording in the background. In the meantime, you can run other commands. If you want to check if the recording is finished, you should use sounddevice.wait():

sd.wait()

If the recording was already finished, this returns immediately; if not, it waits and returns as soon as the recording is finished.

Alternatively, you could have used the blocking argument in the first place:

myrecording = sd.rec(duration * fs, blocking=True)

By default, the recorded array has the data type 'float32' (see sounddevice.default.dtype), but this can be changed with the dtype argument:

myrecording = sd.rec(duration * fs, dtype='float64')

Simultaneous Playback and Recording

To play back an array and record at the same time, use sounddevice.playrec():

myrecording2 = sd.playrec(myarray, fs, channels=2)

The number of output channels is obtained from myarray, but the number of input channels still has to be specified.

Again, default values can be used:

sd.default.samplerate = fs
sd.default.channels = 2
myrecording2 = sd.playrec(myarray)

In this case the number of output channels is still taken from myarray (which may or may not have 2 channels), but the number of input channels is taken from sounddevice.default.channels.

Device Selection

In many cases, the default input/output device(s) will be the one(s) you want, but it is of course possible to choose a different device. Use sounddevice.print_devices() to get a list of supported devices. You can use the corresponding device ID to select a desired device by assigning to sounddevice.default.device or by passing it as device argument to sounddevice.play(), sounddevice.Stream() etc.

Callback Streams

Callback “wire” with sounddevice.Stream:

import sounddevice as sd
duration = 5  # seconds

def callback(indata, outdata, frames, time, status):
    if status:
        print(status)
    outdata[:] = indata

with sd.Stream(channels=2, callback=callback):
    sd.sleep(duration * 1000)

Same thing with sounddevice.RawStream:

import sounddevice as sd
duration = 5  # seconds

def callback(indata, outdata, frames, time, status):
    if status:
        print(status)
    outdata[:] = indata

with sd.RawStream(channels=2, dtype='int24', callback=callback):
    sd.sleep(duration * 1000)

Blocking Read/Write Streams

Coming soon!

Metadata

Release files for sounddevice 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sounddevice 0.2.1
File Size Uploaded Provenance Actions
sounddevice-0.2.1.tar.gz 32.4 kB Without provenance Details for sounddevice-0.2.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for sounddevice 0.2.1
File Actions
sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win_amd64.whl CPython 2.7, PyPy 2.7, CPython 3.5, CPython 3.2, CPython 3.4, Python 3, CPython 3.3, CPython 2.6, PyPy 3.2, Python 2 none Windows x86-64 Details for sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win_amd64.whl
sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win32.whl CPython 3.4, Python 3, Python 2, CPython 2.6, CPython 3.3, PyPy 3.2, CPython 3.2, CPython 2.7, PyPy 2.7, CPython 3.5 none Windows x86-32 Details for sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win32.whl
sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-macosx_10_6_x86_64.whl CPython 3.4, Python 3, CPython 3.3, CPython 2.6, PyPy 3.2, Python 2, CPython 3.2, CPython 2.7, PyPy 2.7, CPython 3.5 none macOS 10.6+ x86-64 Details for sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-macosx_10_6_x86_64.whl
sounddevice-0.2.1-py2.py3-none-any.whl Python 3, Python 2 none any Details for sounddevice-0.2.1-py2.py3-none-any.whl

Total release size: 1.2 MB

Release files / sounddevice-0.2.1.tar.gz

Download URL sounddevice-0.2.1.tar.gz
Size 32.4 kB
Tags Source
SHA-256 checksum
How to use checksums
abb57fc03470bd4a509e8ff8af5323f3b348aab113b1aa306de492e56bdae002
BLAKE2b-256 checksum
How to use checksums
ac0d5f6218e836dd7a0266e8b102935874fd81df619975264b5ca0596548b285
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win_amd64.whl

Download URL sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win_amd64.whl
Size 413.9 kB
Tags CPython 2.6 CPython 2.7 CPython 3.2 CPython 3.3 CPython 3.4 CPython 3.5 PyPy 2.7 PyPy 3.2 Python 2 Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
6ca18c4867de667afd4b9195a689887b7a3e6c15bab5beaf5250c2622353b3ba
BLAKE2b-256 checksum
How to use checksums
a82f3ae4b57e766a6481dd4b3472cf76ded383c3018bf69dc94fcf3db9fc6742
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win32.whl

Download URL sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-win32.whl
Size 405.7 kB
Tags CPython 2.6 CPython 2.7 CPython 3.2 CPython 3.3 CPython 3.4 CPython 3.5 PyPy 2.7 PyPy 3.2 Python 2 Python 3 Windows x86-32
SHA-256 checksum
How to use checksums
32c12cbb60cf6785b4faf7dadaaac7cf0db7b8b4b26e9ff37ec4c276d4c7a67a
BLAKE2b-256 checksum
How to use checksums
de34f60c5eb63138f8eac3148c265e65af38a4b090e820f69b5e1bf40421cdaa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-macosx_10_6_x86_64.whl

Download URL sounddevice-0.2.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.pp27.pp32-none-macosx_10_6_x86_64.whl
Size 231.9 kB
Tags CPython 2.6 CPython 2.7 CPython 3.2 CPython 3.3 CPython 3.4 CPython 3.5 PyPy 2.7 PyPy 3.2 Python 2 Python 3 macOS 10.6+ x86-64
SHA-256 checksum
How to use checksums
a8f5869647bfa887136057ae91885e51be9676d21bc134d18f37575e9584fc41
BLAKE2b-256 checksum
How to use checksums
3ae9577a50b0ffea5a7b2fd293a5493f328dfb98d01a1939799b5161104ef402
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / sounddevice-0.2.1-py2.py3-none-any.whl

Download URL sounddevice-0.2.1-py2.py3-none-any.whl
Size 104.5 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
044cef10bcae6a6023b4dcf761da9defec67816b3c19aee0603e453d13b30c5e
BLAKE2b-256 checksum
How to use checksums
b8dacf18bdfba9da54491d2be03b65643dd4131d09a42d8d6735e1ead87fc68e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for sounddevice 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

5 release files No provenance

0.0.0

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page