Skip to content

Commit 6bc3998

Browse files
mgeiermgeier
committed
DOC: Re-structure "installation" section
1 parent f41bbf2 commit 6bc3998

File tree

1 file changed

+57
-71
lines changed

1 file changed

+57
-71
lines changed

‎README.rst‎

Lines changed: 57 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -13,79 +13,44 @@ Source code repository and issue tracker:
1313
License:
1414
MIT -- see the file ``LICENSE`` for details.
1515

16-
.. image:: https://badge.fury.io/py/sounddevice.svg
17-
:target: https://pypi.python.org/pypi/sounddevice/
16+
Installation
17+
------------
18+
19+
First of all, you'll need Python_.
20+
Any version where CFFI_ is supported should work.
21+
If you don't have Python installed yet, you should get one of the
22+
distributions which already include CFFI and NumPy_ (and many other useful
23+
things), e.g. Anaconda_ or WinPython_.
24+
25+
.. image:: https://anaconda.org/conda-forge/python-sounddevice/badges/version.svg
26+
:target: https://anaconda.org/conda-forge/python-sounddevice
27+
28+
If you are using the ``conda`` package manager (e.g. with Anaconda_ for
29+
Linux/macOS/Windows), you can install the ``sounddevice`` module from the
30+
``conda-forge`` channel::
31+
32+
conda install -c conda-forge python-sounddevice
33+
34+
There are also packages for several other package managers:
1835

1936
.. image:: https://repology.org/badge/vertical-allrepos/python:sounddevice.svg
2037
:target: https://repology.org/metapackage/python:sounddevice
2138

22-
Requirements
23-
------------
24-
25-
Python:
26-
Of course, you'll need Python_.
27-
Any version where CFFI (see below) is supported should work.
28-
If you don't have Python installed yet, you should get one of the
29-
distributions which already include CFFI and NumPy (and many other useful
30-
things), e.g. Anaconda_ or WinPython_.
31-
32-
pip/setuptools:
33-
Those are needed for the installation of the Python module and its
34-
dependencies. Most systems will have these installed already, but if not,
35-
you should install it with your package manager or you can download and
36-
install ``pip`` and ``setuptools`` as described on the `pip installation`_
37-
page.
38-
If you happen to have ``pip`` but not ``setuptools``, use this command::
39-
40-
python3 -m pip install setuptools --user
41-
42-
To upgrade to a newer version of an already installed package (including
43-
``pip`` itself), use the ``--upgrade`` flag.
44-
45-
CFFI:
46-
The `C Foreign Function Interface for Python`_ is used to access the C-API
47-
of the PortAudio library from within Python. It supports CPython 2.6, 2.7,
48-
3.x; and is distributed with PyPy_.
49-
If it's not installed already, you should install it with your package
50-
manager (the package might be called ``python3-cffi`` or similar), or you can
51-
get it with::
52-
53-
python3 -m pip install cffi --user
54-
55-
PortAudio library:
56-
The PortAudio_ library must be installed on your system (and CFFI must be
57-
able to find it). Again, you should use your package manager to install it
58-
(the package might be called ``libportaudio2`` or similar).
59-
If you prefer, you can of course also download the sources and compile the
60-
library yourself. If you are using Mac OS X or Windows, the library will be
61-
installed automagically with *pip* (see "Installation" below).
62-
63-
NumPy (optional):
64-
NumPy_ is only needed if you want to play back and record NumPy arrays.
65-
The classes `sounddevice.RawStream`, `sounddevice.RawInputStream` and
66-
`sounddevice.RawOutputStream` use plain Python buffer objects and don't need
67-
NumPy at all.
68-
If you need NumPy, you should install it with your package manager or use a
69-
Python distribution that already includes NumPy (see above).
70-
You can also install NumPy with ``pip``, but depending on your platform, this
71-
might require a compiler and several additional libraries::
72-
73-
python3 -m pip install NumPy --user
39+
If you are using Windows, you can alternatively install one of the packages
40+
provided at https://www.lfd.uci.edu/~gohlke/pythonlibs/#sounddevice.
41+
The PortAudio library is included in the package and you can get the rest
42+
of the dependencies on the same page.
7443

75-
.. _PortAudio: http://www.portaudio.com/
76-
.. _NumPy: http://www.numpy.org/
77-
.. _Python: https://www.python.org/
78-
.. _Anaconda: https://www.anaconda.com/download/
79-
.. _WinPython: http://winpython.github.io/
80-
.. _C Foreign Function Interface for Python: http://cffi.readthedocs.io/
81-
.. _PyPy: http://pypy.org/
82-
.. _pip installation: https://pip.pypa.io/en/latest/installing/
44+
Note that some of the aforementioned packages may be out-of-date.
45+
You can always get the newest ``sounddevice`` release from PyPI_
46+
(using ``pip``).
47+
If you want to try the latest development version, have a look at the section
48+
about `Contributing`_.
8349

84-
Installation
85-
------------
50+
.. image:: https://badge.fury.io/py/sounddevice.svg
51+
:target: https://pypi.org/project/sounddevice/
8652

87-
Once you have installed the above-mentioned dependencies, you can use pip
88-
to download and install the latest release with a single command::
53+
To install the latest release from PyPI, use::
8954

9055
python3 -m pip install sounddevice --user
9156

@@ -98,10 +63,31 @@ To un-install, use::
9863

9964
python3 -m pip uninstall sounddevice
10065

101-
If you are using Windows, you can alternatively install one of the packages
102-
provided at https://www.lfd.uci.edu/~gohlke/pythonlibs/#sounddevice.
103-
The PortAudio library is also included in the package and you can get the rest
104-
of the dependencies on the same page.
66+
If you install the ``sounddevice`` module with ``pip`` on macOS or Windows, the
67+
PortAudio_ library will be installed automagically.
68+
On other platforms, you might have to install PortAudio with your package
69+
manager (the package might be called ``libportaudio2`` or similar).
70+
71+
You might also have to install CFFI_ (from a package called ``python3-cffi`` or
72+
similar).
73+
74+
NumPy_ is only needed if you want to play back and record NumPy arrays.
75+
The classes `sounddevice.RawStream`, `sounddevice.RawInputStream` and
76+
`sounddevice.RawOutputStream` use plain Python buffer objects and don't need
77+
NumPy at all.
78+
If you need NumPy, you should install it with your package manager (from a
79+
package named ``python3-numpy`` or similar) or use a Python distribution that
80+
already includes NumPy (see above).
81+
You can also install NumPy with ``pip``, but depending on your platform, this
82+
might require a compiler and several additional libraries.
83+
84+
.. _PortAudio: http://www.portaudio.com/
85+
.. _NumPy: http://www.numpy.org/
86+
.. _Python: https://www.python.org/
87+
.. _Anaconda: https://www.anaconda.com/download/
88+
.. _WinPython: http://winpython.github.io/
89+
.. _CFFI: http://cffi.readthedocs.io/
90+
.. _PyPI: https://pypi.org/project/sounddevice/
10591

10692
Usage
10793
-----
@@ -165,7 +151,7 @@ After that, you can drop the additional arguments:
165151

166152
.. code:: python
167153
168-
myrecording = sd.rec(duration * fs)
154+
myrecording = sd.rec(int(duration * fs))
169155
170156
This function also returns immediately but continues recording in the
171157
background. In the meantime, you can run other commands. If you want to check

0 commit comments

Comments
 (0)