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