Skip to content

Commit 8403e2f

Browse files
mgeiermgeier
committed
DOC: Split docs into multiple pages
1 parent 5c2b9bc commit 8403e2f

File tree

7 files changed

+125
-109
lines changed

7 files changed

+125
-109
lines changed

‎README.rst‎

Lines changed: 8 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -13,95 +13,17 @@ like garbage collection and the GIL.
1313
All PortAudio platforms and host APIs are supported.
1414
Runs on any Python version where CFFI is available.
1515

16-
Features:
16+
Online documentation
17+
https://python-rtmixer.readthedocs.io/
1718

18-
* playback of multiple signals at the same time (that's why it's called "mixer")
19+
Source code repository
20+
https://github.com/spatialaudio/python-rtmixer
1921

20-
* play from buffer, play from ringbuffer
21-
22-
* record into buffer, record into ringbuffer
23-
24-
* multichannel support
25-
26-
* NumPy arrays with data type ``'float32'`` can be easily used (via the buffer
27-
protocol) as long as they are C-contiguous
28-
29-
* fixed latency playback, (close to) no jitter (optional)
30-
31-
* to be verified ...
32-
33-
* sample-accurate playback/recording (with known offset)
34-
35-
* to be verified ...
36-
37-
* non-blocking callback function, using PortAudio ringbuffers
38-
39-
* all memory allocations/deallocations happen outside the audio callback
40-
41-
Planned features:
42-
43-
* meticulous reporting of overruns/underruns
44-
45-
* loopback tests to verify correct operation and accurate latency values
46-
47-
* fade in/out?
48-
49-
* loop?
50-
51-
* playlist/queue?
52-
53-
Out of scope:
54-
55-
* reading from/writing to files (use e.g. the soundfile_ module)
56-
57-
* realtime signal processing (inside the audio callback)
58-
59-
* signal generators
60-
61-
* multiple mixer instances (some PortAudio host APIs only support one stream at
62-
a time)
63-
64-
* resampling (apart from what PortAudio does)
65-
66-
* fast forward/rewind
67-
68-
* panning/balance
69-
70-
* audio/video synchronization
71-
72-
Somewhat similar projects:
73-
74-
* https://github.com/nwhitehead/swmixer
75-
* https://github.com/nvahalik/PyAudioMixer
76-
* http://www.pygame.org/docs/ref/mixer.html
77-
78-
Installation
79-
------------
80-
81-
On Windows, macOS, and Linux you can install a precompiled wheel with::
82-
83-
python3 -m pip install rtmixer
84-
85-
This will install ``rtmixer`` and its dependencies, including ``sounddevice``.
86-
87-
.. note:: On Linux, to use ``sounddevice`` and ``rtmixer`` you will need to
88-
have PortAudio installed, e.g. via ``sudo apt install libportaudio2``.
89-
On other platforms, PortAudio comes bundled with ``sounddevice``.
90-
91-
Developers can install in editable mode with some variant of::
92-
93-
git clone https://github.com/spatialaudio/python-rtmixer
94-
cd python-rtmixer
95-
git submodule update --init
96-
python3 -m pip install -e .
97-
98-
Usage
99-
-----
100-
101-
See the list of `examples on GitHub`_.
22+
Somewhat similar projects
23+
* https://github.com/nwhitehead/swmixer
24+
* https://github.com/nvahalik/PyAudioMixer
25+
* http://www.pygame.org/docs/ref/mixer.html
10226

10327
.. _PortAudio: http://portaudio.com/
10428
.. _sounddevice: http://python-sounddevice.readthedocs.io/
10529
.. _CFFI: http://cffi.readthedocs.io/
106-
.. _soundfile: http://pysoundfile.readthedocs.io/
107-
.. _examples on GitHub: https://github.com/spatialaudio/python-rtmixer/tree/master/examples

‎doc/api.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
API Documentation
2+
=================
3+
4+
.. automodule:: rtmixer
5+
6+
.. autoclass:: Mixer
7+
:members: play_buffer, play_ringbuffer, actions, cancel, wait, stats,
8+
fetch_and_reset_stats
9+
:undoc-members:
10+
11+
.. autoclass:: Recorder
12+
:members:
13+
:undoc-members:
14+
15+
.. autoclass:: MixerAndRecorder
16+
:members:
17+
:undoc-members:
18+
19+
.. autoclass:: RingBuffer
20+
:inherited-members:

‎doc/features.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
Features
2+
========
3+
4+
* playback of multiple signals at the same time (that's why it's called "mixer")
5+
6+
* play from buffer, play from ringbuffer
7+
8+
* record into buffer, record into ringbuffer
9+
10+
* multichannel support
11+
12+
* NumPy arrays with data type ``'float32'`` can be easily used (via the buffer
13+
protocol) as long as they are C-contiguous
14+
15+
* fixed latency playback, (close to) no jitter (optional)
16+
17+
* to be verified ...
18+
19+
* sample-accurate playback/recording (with known offset)
20+
21+
* to be verified ...
22+
23+
* non-blocking callback function, using PortAudio ringbuffers
24+
25+
* all memory allocations/deallocations happen outside the audio callback
26+
27+
28+
Planned Features
29+
----------------
30+
31+
* meticulous reporting of overruns/underruns
32+
33+
* loopback tests to verify correct operation and accurate latency values
34+
35+
* fade in/out?
36+
37+
* loop?
38+
39+
* playlist/queue?
40+
41+
42+
Out Of Scope
43+
------------
44+
45+
* reading from/writing to files (use e.g. the soundfile_ module)
46+
47+
* realtime signal processing (inside the audio callback)
48+
49+
* signal generators
50+
51+
* multiple mixer instances (some PortAudio host APIs only support one stream at
52+
a time)
53+
54+
* resampling (apart from what PortAudio does)
55+
56+
* fast forward/rewind
57+
58+
* panning/balance
59+
60+
* audio/video synchronization
61+
62+
.. _soundfile: https://python-soundfile.readthedocs.io/

‎doc/index.rst‎

Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,14 @@
11
.. include:: ../README.rst
22

3-
API Documentation
4-
-----------------
3+
----
54

6-
.. automodule:: rtmixer
5+
.. toctree::
76

8-
.. autoclass:: Mixer
9-
:members: play_buffer, play_ringbuffer, actions, cancel, wait, stats,
10-
fetch_and_reset_stats
11-
:undoc-members:
12-
13-
.. autoclass:: Recorder
14-
:members:
15-
:undoc-members:
16-
17-
.. autoclass:: MixerAndRecorder
18-
:members:
19-
:undoc-members:
20-
21-
.. autoclass:: RingBuffer
22-
:inherited-members:
7+
features
8+
installation
9+
usage
10+
api
2311

2412
.. only:: html
2513

26-
Index
27-
-----
28-
29-
:ref:`genindex`
14+
:ref:`genindex`

‎doc/installation.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Installation
2+
============
3+
4+
On Windows, macOS, and Linux you can install a precompiled wheel with::
5+
6+
python3 -m pip install rtmixer
7+
8+
This will install ``rtmixer`` and its dependencies, including ``sounddevice``.
9+
10+
.. note:: On Linux, to use ``sounddevice`` and ``rtmixer`` you will need to
11+
have PortAudio installed, e.g. via ``sudo apt install libportaudio2``.
12+
On other platforms, PortAudio comes bundled with ``sounddevice``.
13+
14+
Developers can install in editable mode with some variant of::
15+
16+
git clone https://github.com/spatialaudio/python-rtmixer
17+
cd python-rtmixer
18+
git submodule update --init
19+
python3 -m pip install -e .

‎doc/usage.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Usage
2+
=====
3+
4+
See the list of `examples on GitHub`_.
5+
6+
.. _examples on GitHub: https://github.com/spatialaudio/python-rtmixer/
7+
tree/master/examples
8+

‎src/rtmixer.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"""Reliable low-latency audio playback and recording.
22
3-
http://python-rtmixer.readthedocs.io/
3+
https://python-rtmixer.readthedocs.io/
44
55
"""
66
__version__ = '0.1.1'

0 commit comments

Comments
 (0)