Contributing§

If you find bugs, errors, omissions or other things that need improvement, please create an issue or a pull request at https://github.com/spatialaudio/python-sounddevice/. Contributions are always welcome!

Reporting Problems§

When creating an issue at https://github.com/spatialaudio/python-sounddevice/issues, please make sure to provide as much useful information as possible.

You can use Markdown formatting to show Python code, e.g.

I have created a script named `my_script.py`:

```python
import sounddevice as sd

fs = 48000
duration = 1.5

data = sd.rec(int(duration * fs), channels=99)
sd.wait()
print(data.shape)
```

Please provide minimal code (remove everything that’s not necessary to show the problem), but make sure that the code example still has everything that’s needed to run it, including all import statements.

You should of course also show what happens when you run your code, e.g.

Running my script, I got this error:

```
$ python my_script.py
Expression 'parameters->channelCount <= maxChans' failed in 'src/hostapi/alsa/pa_linux_alsa.c', line: 1514
Expression 'ValidateParameters( inputParameters, hostApi, StreamDirection_In )' failed in 'src/hostapi/alsa/pa_linux_alsa.c', line: 2818
Traceback (most recent call last):
  File "my_script.py", line 6, in <module>
    data = sd.rec(int(duration * fs), channels=99)
...
sounddevice.PortAudioError: Error opening InputStream: Invalid number of channels [PaErrorCode -9998]
```

Please remember to provide the full command invocation and the full output. You should only remove lines of output when you know they are irrelevant.

You should also mention the operating system and host API you are using (e.g. “Linux/ALSA” or “macOS/Core Audio” or “Windows/WASAPI”).

If your problem is related to a certain hardware device, you should provide the list of devices as reported by

python -m sounddevice

If your problem has to do with the version of the PortAudio library you are using, you should provide the output of this script:

import sounddevice as sd
print(sd._libname)
print(sd.get_portaudio_version())

If you don’t want to clutter the issue description with a huge load of gibberish, you can use the <details> HTML tag to show some content only on demand:

<details>

```
$ python -m sounddevice
  0 Built-in Line Input, Core Audio (2 in, 0 out)
> 1 Built-in Digital Input, Core Audio (2 in, 0 out)
< 2 Built-in Output, Core Audio (0 in, 2 out)
  3 Built-in Line Output, Core Audio (0 in, 2 out)
  4 Built-in Digital Output, Core Audio (0 in, 2 out)
```

</details>

Development Installation§

Instead of pip-installing the latest release from PyPI, you should get the newest development version (a.k.a. “master”) from Github:

git clone --recursive https://github.com/spatialaudio/python-sounddevice.git
cd python-sounddevice
python -m pip install -e .

This way, your installation always stays up-to-date, even if you pull new changes from the Github repository.

Whenever the file sounddevice_build.py changes (either because you edited it or it was updated by pulling from Github or switching branches), you have to run the last command again.

If you used the --recursive option when cloning, the dynamic libraries for macOS and Windows should already be available. If not, you can get the submodule with:

git submodule update --init

Building the Documentation§

If you make changes to the documentation, you can locally re-create the HTML pages using Sphinx. You can install it and a few other necessary packages with:

python -m pip install -r doc/requirements.txt

To (re-)build the HTML files, use:

python -m sphinx doc _build

The generated files will be available in the directory _build/.

If you additionally install sphinx-autobuild, you can run Sphinx automatically on any changes and conveniently auto-reload the changed pages in your browser:

python -m sphinx_autobuild doc _build --open-browser