Skip to main content

Play and Record Sound with Python

Project description

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/

License:

MIT – see the file LICENSE for details.

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. The package may be called libportaudio2 or similar. 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():

myrecording = 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
myrecording = 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.query_devices() to get a list of supported devices. The same list can be obtained from a terminal by typing the command

python -m sounddevice

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.

Instead of the numerical device ID, you can also use a space-separated list of case-insensitive substrings of the device name (and the host API name, if needed). See sounddevice.default.device for details.

import sounddevice as sd
sd.default.samplerate = 44100
sd.default.device = 'digital output'
sd.play(myarray)

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

Instead of using a callback function, you can also use the blocking methods sounddevice.Stream.read() and sounddevice.Stream.write() (and of course the corresponding methods in sounddevice.InputStream, sounddevice.OutputStream, sounddevice.RawStream, sounddevice.RawInputStream and sounddevice.RawOutputStream).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sounddevice-0.3.1.tar.gz (34.4 kB view details)

Uploaded Source

Built Distributions

sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-win_amd64.whl (421.1 kB view details)

Uploaded CPython 2.6CPython 2.7CPython 3.2CPython 3.3CPython 3.4CPython 3.5CPython 3.6PyPyPython 2Python 3Windows x86-64

sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-win32.whl (412.9 kB view details)

Uploaded CPython 2.6CPython 2.7CPython 3.2CPython 3.3CPython 3.4CPython 3.5CPython 3.6PyPyPython 2Python 3Windows x86

sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-macosx_10_6_x86_64.whl (239.2 kB view details)

Uploaded CPython 2.6CPython 2.7CPython 3.2CPython 3.3CPython 3.4CPython 3.5CPython 3.6PyPyPython 2Python 3macOS 10.6+ x86-64

sounddevice-0.3.1-py2.py3-none-any.whl (111.2 kB view details)

Uploaded Python 2Python 3

File details

Details for the file sounddevice-0.3.1.tar.gz.

File metadata

  • Download URL: sounddevice-0.3.1.tar.gz
  • Upload date:
  • Size: 34.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for sounddevice-0.3.1.tar.gz
Algorithm Hash digest
SHA256 8e5a6816b369c7aea77e06092b2fee99c8b6efbeef4851f53ea3cb208a7607f5
MD5 84479723c319162d993def4176201141
BLAKE2b-256 5b6cc4827069dc239b321c682bac4898624586653fa4b996254c70b2d5047a3a

See more details on using hashes here.

File details

Details for the file sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-win_amd64.whl.

File metadata

File hashes

Hashes for sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-win_amd64.whl
Algorithm Hash digest
SHA256 d6a69d7c96c3d352539848af94b7a410605ffcc0272c2f13a1b83fe28a730274
MD5 d5a6c11c52c232ec1d7004302f5e60b0
BLAKE2b-256 5f00b643eb7403de5dc827a69db9ebd2b3b2fe2358770790eae6f8ce6a408844

See more details on using hashes here.

File details

Details for the file sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-win32.whl.

File metadata

File hashes

Hashes for sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-win32.whl
Algorithm Hash digest
SHA256 5c224c91290a868452efbe5ef1dec11d47d6b72afe3b4e9d63706c33ea32d5a7
MD5 cddb84aaf256a323a240a386877eeccc
BLAKE2b-256 e06054d9feef90bbe3daf3d88dc48f22e2368b850c018e463aa082a092528adf

See more details on using hashes here.

File details

Details for the file sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-macosx_10_6_x86_64.whl.

File metadata

File hashes

Hashes for sounddevice-0.3.1-py2.py3.cp26.cp27.cp32.cp33.cp34.cp35.cp36.pp27.pp32.pp33.pp34.pp35.pp36-none-macosx_10_6_x86_64.whl
Algorithm Hash digest
SHA256 802b62d412fa7f9b212b127161abf44cc361e1951920071995c9f706d55ac6ce
MD5 8e1bc9f08f74476ba1caff4c3e74781d
BLAKE2b-256 ce3a31770eb36b796e561ac361b49b684eef36cfb5d13c5d63b39193fa18f60a

See more details on using hashes here.

File details

Details for the file sounddevice-0.3.1-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for sounddevice-0.3.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 07ba05e262929af6701047d79d402496da1969d0f199ba91feb21673b5d05fb5
MD5 149789d8f801d2d37d1f3dc12c251a3e
BLAKE2b-256 a67c592684c7d3da1ec1b2d2a12b9f41063d6ddc6c1f148ce6d645d2a58a87b8

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page