|
| 1 | +Play and Record Sound with Python |
| 2 | +================================= |
| 3 | + |
| 4 | +This Python_ module provides bindings for the PortAudio_ library and a few |
| 5 | +convenience functions to play and record NumPy_ arrays containing audio signals. |
| 6 | + |
| 7 | +Documentation: |
| 8 | + http://python-sounddevice.rtfd.org/ |
| 9 | + |
| 10 | +Code: |
| 11 | + http://github.com/spatialaudio/python-sounddevice/ |
| 12 | + |
| 13 | +Python Package Index: |
| 14 | + http://pypi.python.org/pypi/sounddevice/ |
| 15 | + |
| 16 | +Requirements |
| 17 | +------------ |
| 18 | + |
| 19 | +Python: |
| 20 | + Of course, you'll need Python_. |
| 21 | + Any version where CFFI (see below) is supported should work. |
| 22 | + If you don't have Python installed yet, you should get one of the |
| 23 | + distributions which already include CFFI and NumPy (and many other useful |
| 24 | + things), e.g. Anaconda_ or WinPython_. |
| 25 | + |
| 26 | +pip/setuptools: |
| 27 | + Those are needed for the installation of the Python module and its |
| 28 | + dependencies. Most systems will have these installed already, but if not, |
| 29 | + you should install it with your package manager or you can download and |
| 30 | + install pip and setuptools as described on the `pip installation`_ page. |
| 31 | + If you happen to have pip but not setuptools, use this command:: |
| 32 | + |
| 33 | + pip install setuptools --user |
| 34 | + |
| 35 | +CFFI: |
| 36 | + The `C Foreign Function Interface for Python`_ is used to access the C-API |
| 37 | + of the PortAudio library from within Python. It supports CPython 2.6, 2.7, |
| 38 | + 3.x; and is distributed with PyPy_ 2.0 beta2 or later. |
| 39 | + You should install it with your package manager (if it's not installed |
| 40 | + already), or you can get it with:: |
| 41 | + |
| 42 | + pip install cffi --user |
| 43 | + |
| 44 | +PortAudio library: |
| 45 | + The PortAudio_ library must be installed on your system (and CFFI must be |
| 46 | + able to find it). Again, you should use your package manager to install it. |
| 47 | + If you prefer, you can of course also download the sources and compile the |
| 48 | + library yourself. |
| 49 | + |
| 50 | +NumPy (optional): |
| 51 | + NumPy_ is only needed if you want to play back and record NumPy arrays. |
| 52 | + The classes `sounddevice.RawStream`, `sounddevice.RawInputStream` and |
| 53 | + `sounddevice.RawOutputStream` use plain Python buffer objects and don't need |
| 54 | + NumPy at all. |
| 55 | + If you need NumPy, you should install it with your package manager or use a |
| 56 | + Python distribution that already includes NumPy (see above). |
| 57 | + Installing NumPy with pip is not recommended. |
| 58 | + |
| 59 | +.. _PortAudio: http://www.portaudio.com/ |
| 60 | +.. _NumPy: http://www.numpy.org/ |
| 61 | +.. _Python: http://www.python.org/ |
| 62 | +.. _Anaconda: http://docs.continuum.io/anaconda/ |
| 63 | +.. _WinPython: http://winpython.github.io/ |
| 64 | +.. _C Foreign Function Interface for Python: http://cffi.readthedocs.org/ |
| 65 | +.. _PyPy: http://pypy.org/ |
| 66 | +.. _pip installation: http://www.pip-installer.org/en/latest/installing.html |
| 67 | + |
| 68 | +Installation |
| 69 | +------------ |
| 70 | + |
| 71 | +Once you have installed the above-mentioned dependencies, you can use pip |
| 72 | +to download and install the latest release with a single command:: |
| 73 | + |
| 74 | + pip install sounddevice --user |
| 75 | + |
| 76 | +If you want to install it system-wide for all users (assuming you have the |
| 77 | +necessary rights), you can just drop the ``--user`` option. |
| 78 | + |
| 79 | +To un-install, use:: |
| 80 | + |
| 81 | + pip uninstall sounddevice |
| 82 | + |
| 83 | +Usage |
| 84 | +----- |
| 85 | + |
| 86 | +First, import the module: |
| 87 | + |
| 88 | +>>> import sounddevice as sd |
| 89 | + |
| 90 | +Playback |
| 91 | +^^^^^^^^ |
| 92 | + |
| 93 | +Assuming you have a NumPy array named ``myarray`` holding audio data with a |
| 94 | +sampling frequency of ``fs`` (in the most cases this will be 44100 or 48000 |
| 95 | +frames per second), you can play it back with `sounddevice.play()`: |
| 96 | + |
| 97 | +>>> sd.play(myarray, fs) |
| 98 | + |
| 99 | +This function returns immediately but continues playing the audio signal in the |
| 100 | +background. You can stop playback with `sounddevice.stop()`: |
| 101 | + |
| 102 | +>>> sd.stop() |
| 103 | + |
| 104 | +If you know that you will use the same sampling frequency for a while, you can |
| 105 | +set it as default using `sounddevice.default.samplerate`: |
| 106 | + |
| 107 | +>>> sd.default.samplerate = fs |
| 108 | + |
| 109 | +After that, you can drop the *samplerate* argument: |
| 110 | + |
| 111 | +>>> sd.play(myarray) |
| 112 | + |
| 113 | +Recording |
| 114 | +^^^^^^^^^ |
| 115 | + |
| 116 | +To record audio data from your sound device into a NumPy array, use |
| 117 | +`sounddevice.rec()`: |
| 118 | + |
| 119 | +>>> duration = 10 # seconds |
| 120 | +>>> myrecording = sd.rec(duration * fs, samplerate=fs, channels=2) |
| 121 | + |
| 122 | +Again, for repeated use you can set defaults using `sounddevice.default`: |
| 123 | + |
| 124 | +>>> sd.default.samplerate = fs |
| 125 | +>>> sd.default.channels = 2 |
| 126 | + |
| 127 | +After that, you can drop the additional arguments: |
| 128 | + |
| 129 | +>>> myrecording = sd.rec(duration * fs) |
| 130 | + |
| 131 | +This function also returns immediately but continues recording in the |
| 132 | +background. In the meantime, you can run other commands. If you want to check if |
| 133 | +the recording is finished, you should use `sounddevice.wait()`: |
| 134 | + |
| 135 | +>>> sd.wait() |
| 136 | + |
| 137 | +If the recording was already finished, this returns immediately; if not, it |
| 138 | +waits and returns as soon as the recording is finished. |
| 139 | + |
| 140 | +Alternatively, you could have used the *blocking* argument in the first place: |
| 141 | + |
| 142 | +>>> myrecording = sd.rec(duration * fs, blocking=True) |
| 143 | + |
| 144 | +By default, the recorded array has the data type ``'float32'`` (see |
| 145 | +`sounddevice.default.dtype`), but this can be changed with the *dtype* argument: |
| 146 | + |
| 147 | +>>> myrecording = sd.rec(duration * fs, dtype='float64') |
| 148 | + |
| 149 | +Simultaneous Playback and Recording |
| 150 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 151 | + |
| 152 | +To play back an array and record at the same time, use `sounddevice.playrec()`: |
| 153 | + |
| 154 | +>>> myrecording2 = sd.playrec(myarray, fs, input_channels=2) |
| 155 | + |
| 156 | +The number of output channels is obtained from ``myarray``, but the number of |
| 157 | +input channels still has to be specified. |
| 158 | + |
| 159 | +Again, default values can be used: |
| 160 | + |
| 161 | +>>> sd.default.samplerate = fs |
| 162 | +>>> sd.default.channels = 2 |
| 163 | +>>> myrecording2 = sd.playrec(myarray) |
| 164 | + |
| 165 | +In this case the number of output channels is still taken from ``myarray`` |
| 166 | +(which may or may not have 2 channels), but the number of input channels is |
| 167 | +taken from `sounddevice.default.channels`. |
| 168 | + |
| 169 | +Device Selection |
| 170 | +^^^^^^^^^^^^^^^^ |
| 171 | + |
| 172 | +In many cases, the default input/output device(s) will be the one(s) you want, |
| 173 | +but it is of course possible to choose a different device. |
| 174 | +Use `sounddevice.print_devices()` to get a list of supported devices. |
| 175 | +You can use the corresponding device ID to select a desired device by assigning |
| 176 | +to `sounddevice.default.device` or by passing it as *device* argument to |
| 177 | +`sounddevice.play()`, `sounddevice.Stream()` etc. |
| 178 | + |
| 179 | +Callback Streams |
| 180 | +^^^^^^^^^^^^^^^^ |
| 181 | + |
| 182 | +Callback "wire" with `sounddevice.Stream`:: |
| 183 | + |
| 184 | + import sounddevice as sd |
| 185 | + duration = 5 # seconds |
| 186 | + |
| 187 | + def callback(indata, outdata, frames, time, status): |
| 188 | + if status: |
| 189 | + print(status) |
| 190 | + outdata[:] = indata |
| 191 | + |
| 192 | + with sd.Stream(channels=2, callback=callback): |
| 193 | + sd.sleep(duration * 1000) |
| 194 | + |
| 195 | +Same thing with `sounddevice.RawStream`:: |
| 196 | + |
| 197 | + import sounddevice as sd |
| 198 | + duration = 5 # seconds |
| 199 | + |
| 200 | + def callback(indata, outdata, frames, time, status): |
| 201 | + if status: |
| 202 | + print(status) |
| 203 | + outdata[:] = indata |
| 204 | + |
| 205 | + with sd.RawStream(channels=2, dtype='int24', callback=callback): |
| 206 | + sd.sleep(duration * 1000) |
| 207 | + |
| 208 | +.. note:: We are using 24-bit samples here for no particular reason |
| 209 | + (just because we can). |
| 210 | + |
| 211 | +Blocking Read/Write Streams |
| 212 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 213 | + |
| 214 | +Coming soon! |
| 215 | + |
| 216 | +More Examples |
| 217 | +^^^^^^^^^^^^^ |
| 218 | + |
| 219 | +Have a look in the ``examples/`` directory. |
| 220 | + |
| 221 | +Copyright Information |
| 222 | +--------------------- |
| 223 | + |
| 224 | +python-sounddevice (MIT License) |
| 225 | + Copyright (c) 2015 Matthias Geier |
| 226 | + |
| 227 | +PortAudio_ Portable Real-Time Audio Library (MIT License) |
| 228 | + Copyright (c) 1999-2011 Ross Bencina and Phil Burk |
0 commit comments