1Contributing 2============ 3 4If you find bugs, errors, omissions or other things that need improvement, 5please create an issue or a pull request at 6https://github.com/spatialaudio/python-sounddevice/. 7Contributions are always welcome! 8 9 10Reporting Problems 11------------------ 12 13When creating an issue at 14https://github.com/spatialaudio/python-sounddevice/issues, 15please make sure to provide as much useful information as possible. 16 17You can use Markdown formatting to show Python code, e.g. :: 18 19 I have created a script named `my_script.py`: 20 21 ```python 22 import sounddevice as sd 23 24 fs = 48000 25 duration = 1.5 26 27 data = sd.rec(int(duration * fs), channels=99) 28 sd.wait() 29 print(data.shape) 30 ``` 31 32Please provide minimal code 33(remove everything that's not necessary to show the problem), 34but make sure that the code example still has everything that's needed to run it, 35including all ``import`` statements. 36 37You should of course also show what happens when you run your code, e.g. :: 38 39 Running my script, I got this error: 40 41 ``` 42 $ python3 my_script.py 43 Expression 'parameters->channelCount <= maxChans' failed in 'src/hostapi/alsa/pa_linux_alsa.c', line: 1514 44 Expression 'ValidateParameters( inputParameters, hostApi, StreamDirection_In )' failed in 'src/hostapi/alsa/pa_linux_alsa.c', line: 2818 45 Traceback (most recent call last): 46 File "my_script.py", line 6, in <module> 47 data = sd.rec(int(duration * fs), channels=99) 48 ... 49 sounddevice.PortAudioError: Error opening InputStream: Invalid number of channels [PaErrorCode -9998] 50 ``` 51 52Please remember to provide the full command invocation and the full output. 53You should only remove lines of output when you know they are irrelevant. 54 55You should also mention the operating system and host API you are using 56(e.g. "Linux/ALSA" or "macOS/Core Audio" or "Windows/WASAPI"). 57 58If your problem is related to a certain hardware device, 59you should provide the list of devices as reported by :: 60 61 python3 -m sounddevice 62 63If your problem has to do with the version of the PortAudio library you are using, 64you should provide the output of this script:: 65 66 import sounddevice as sd 67 print(sd._libname) 68 print(sd.get_portaudio_version()) 69 70If you don't want to clutter the issue description with a huge load of gibberish, 71you can use the ``<details>`` HTML tag to show some content only on demand:: 72 73 <details> 74 75 ``` 76 $ python3 -m sounddevice 77 0 Built-in Line Input, Core Audio (2 in, 0 out) 78 > 1 Built-in Digital Input, Core Audio (2 in, 0 out) 79 < 2 Built-in Output, Core Audio (0 in, 2 out) 80 3 Built-in Line Output, Core Audio (0 in, 2 out) 81 4 Built-in Digital Output, Core Audio (0 in, 2 out) 82 ``` 83 84 </details> 85 86 87Development Installation 88------------------------ 89 90Instead of pip-installing the latest release from PyPI_, you should get the 91newest development version (a.k.a. "master") from Github_:: 92 93 git clone --recursive https://github.com/spatialaudio/python-sounddevice.git 94 cd python-sounddevice 95 python3 -m pip install -e . 96 97.. _PyPI: https://pypi.org/project/sounddevice/ 98.. _Github: https://github.com/spatialaudio/python-sounddevice/ 99 100This way, your installation always stays up-to-date, even if you pull new 101changes from the Github repository. 102 103Whenever the file ``sounddevice_build.py`` changes (either because you edited it 104or it was updated by pulling from Github or switching branches), you have to run 105the last command again. 106 107If you used the ``--recursive`` option when cloning, the dynamic libraries for 108*macOS* and *Windows* should already be available. 109If not, you can get the submodule with:: 110 111 git submodule update --init 112 113 114Building the Documentation 115-------------------------- 116 117If you make changes to the documentation, you can locally re-create the HTML 118pages using Sphinx_. 119You can install it and a few other necessary packages with:: 120 121 python3 -m pip install -r doc/requirements.txt 122 123To (re-)build the HTML files, use:: 124 125 python3 setup.py build_sphinx 126 127The generated files will be available in the directory ``build/sphinx/html/``. 128 129.. _Sphinx: https://www.sphinx-doc.org/ 130