Skip to content

Commit 0ce9f34

Browse files
mgeiermgeier
committed
DOC: split into multiple HTML pages
1 parent 581acce commit 0ce9f34

File tree

9 files changed

+236
-238
lines changed

9 files changed

+236
-238
lines changed

‎README.rst‎

Lines changed: 2 additions & 203 deletions
Original file line numberDiff line numberDiff line change
@@ -1,216 +1,15 @@
11
JACK Audio Connection Kit (JACK) Client for Python
22
==================================================
33

4-
This Python module provides bindings for the JACK_ library.
4+
This Python module (named ``jack``) provides bindings for the JACK_ library.
55

66
Documentation:
77
https://jackclient-python.readthedocs.io/
88

9-
Code:
9+
Source code and issue tracker:
1010
https://github.com/spatialaudio/jackclient-python/
1111

1212
License:
1313
MIT -- see the file ``LICENSE`` for details.
1414

15-
.. image:: https://badge.fury.io/py/JACK-Client.svg
16-
:target: https://pypi.org/project/JACK-Client/
17-
18-
Requirements
19-
------------
20-
21-
Python:
22-
Of course, you'll need Python_. More specifically, you'll need Python 3.
23-
If you don't have Python installed yet, you should get one of the
24-
distributions which already include CFFI and NumPy (and many other useful
25-
things), e.g. Anaconda_ or WinPython_.
26-
27-
pip/setuptools:
28-
Those are needed for the installation of the Python module and its
29-
dependencies. Most systems will have these installed already, but if not,
30-
you should install it with your package manager or you can download and
31-
install ``pip`` and ``setuptools`` as described on the `pip installation`_
32-
page.
33-
If you happen to have ``pip`` but not ``setuptools``, use this command::
34-
35-
python3 -m pip install setuptools
36-
37-
To upgrade to a newer version of an already installed package (including
38-
``pip`` itself), use the ``--upgrade`` flag.
39-
40-
CFFI:
41-
The `C Foreign Function Interface for Python`_ is used to access the C-API
42-
of the JACK library from within Python. It is supported on CPython
43-
and is distributed with PyPy_.
44-
If it's not installed already, you should install it with your package
45-
manager (the package might be called ``python3-cffi`` or similar), or you can
46-
get it with::
47-
48-
python3 -m pip install cffi
49-
50-
JACK library:
51-
The JACK_ library must be installed on your system (and CFFI must be able
52-
to find it). Again, you should use your package manager to install it.
53-
Make sure you install the JACK daemon (called ``jackd``). This will also
54-
install the JACK library package.
55-
If you don't have a package manager, you can try one of the binary installers
56-
from the `JACK download page`_.
57-
If you prefer, you can of course also download the sources and compile
58-
everything locally.
59-
60-
NumPy (optional):
61-
NumPy_ is only needed if you want to access the input and output buffers in
62-
the process callback as NumPy arrays.
63-
The only place where NumPy is needed is `jack.OwnPort.get_array()`.
64-
If you need NumPy, you should install it with your package manager or use a
65-
Python distribution that already includes NumPy (see above).
66-
You can also install NumPy with ``pip``, but depending on your platform, this
67-
might require a compiler and several additional libraries::
68-
69-
python3 -m pip install NumPy
70-
7115
.. _JACK: https://jackaudio.org/
72-
.. _NumPy: https://numpy.org/
73-
.. _Python: https://www.python.org/
74-
.. _Anaconda: https://www.anaconda.com/products/individual#Downloads
75-
.. _WinPython: http://winpython.github.io/
76-
.. _C Foreign Function Interface for Python: https://cffi.readthedocs.org/
77-
.. _PyPy: https://www.pypy.org/
78-
.. _JACK download page: https://jackaudio.org/downloads/
79-
.. _pip installation: https://pip.pypa.io/en/latest/installing/
80-
81-
Installation
82-
------------
83-
84-
Once you have installed the above-mentioned dependencies, you can use pip
85-
to download and install the latest release with a single command::
86-
87-
python3 -m pip install JACK-Client
88-
89-
Depending on your Python installation,
90-
you may have to use ``python`` instead of ``python3``.
91-
If you have installed the module already, you can use the ``--upgrade`` flag to
92-
get the newest release.
93-
94-
To un-install, use::
95-
96-
python3 -m pip uninstall JACK-Client
97-
98-
Usage
99-
-----
100-
101-
First, import the module:
102-
103-
>>> import jack
104-
105-
Then, you most likely want to create a new `jack.Client`:
106-
107-
>>> client = jack.Client('MyGreatClient')
108-
109-
You probably want to create some audio input and output ports, too:
110-
111-
>>> client.inports.register('input_1')
112-
jack.OwnPort('MyGreatClient:input_1')
113-
>>> client.outports.register('output_1')
114-
jack.OwnPort('MyGreatClient:output_1')
115-
116-
As you can see, these functions return the newly created port.
117-
If you want, you can save it for later:
118-
119-
>>> in2 = client.inports.register('input_2')
120-
>>> out2 = client.outports.register('output_2')
121-
122-
To see what you can do with the returned objects, have a look at the
123-
documentation of the class `jack.OwnPort`.
124-
125-
In case you forgot, you should remind yourself about the ports you just created:
126-
127-
>>> client.inports
128-
[jack.OwnPort('MyGreatClient:input_1'), jack.OwnPort('MyGreatClient:input_2')]
129-
>>> client.outports
130-
[jack.OwnPort('MyGreatClient:output_1'), jack.OwnPort('MyGreatClient:output_2')]
131-
132-
Have a look at the documentation of the class `jack.Ports` to get more detailed
133-
information about these lists of ports.
134-
135-
If you have selected an appropriate driver in your JACK settings, you can also
136-
create MIDI ports:
137-
138-
>>> client.midi_inports.register('midi_in')
139-
jack.OwnMidiPort('MyGreatClient:midi_in')
140-
>>> client.midi_outports.register('midi_out')
141-
jack.OwnMidiPort('MyGreatClient:midi_out')
142-
143-
You can check what other JACK ports are available (your output may be
144-
different):
145-
146-
>>> client.get_ports() # doctest: +SKIP
147-
[jack.Port('system:capture_1'),
148-
jack.Port('system:capture_2'),
149-
jack.Port('system:playback_1'),
150-
jack.Port('system:playback_2'),
151-
jack.MidiPort('system:midi_capture_1'),
152-
jack.MidiPort('system:midi_playback_1'),
153-
jack.OwnPort('MyGreatClient:input_1'),
154-
jack.OwnPort('MyGreatClient:output_1'),
155-
jack.OwnPort('MyGreatClient:input_2'),
156-
jack.OwnPort('MyGreatClient:output_2'),
157-
jack.OwnMidiPort('MyGreatClient:midi_in'),
158-
jack.OwnMidiPort('MyGreatClient:midi_out')]
159-
160-
Note that the ports you created yourself are of type `jack.OwnPort` and
161-
`jack.OwnMidiPort`, while other ports are merely of type `jack.Port` and
162-
`jack.MidiPort`, respectively.
163-
164-
You can also be more specific when looking for ports:
165-
166-
>>> client.get_ports(is_audio=True, is_output=True, is_physical=True)
167-
[jack.Port('system:capture_1'), jack.Port('system:capture_2')]
168-
169-
You can even use regular expressions to search for ports:
170-
171-
>>> client.get_ports('Great.*2$')
172-
[jack.OwnPort('MyGreatClient:input_2'), jack.OwnPort('MyGreatClient:output_2')]
173-
174-
If you want, you can also set all kinds of callback functions for your client.
175-
For details see the documentation for the class `jack.Client` and the example
176-
applications in the ``examples/`` directory.
177-
178-
Once you are ready to run, you should activate your client:
179-
180-
>>> client.activate()
181-
182-
As soon as the client is activated, you can make connections (this isn't
183-
possible before activating the client):
184-
185-
>>> client.connect('system:capture_1', 'MyGreatClient:input_1')
186-
>>> client.connect('MyGreatClient:output_1', 'system:playback_1')
187-
188-
You can also use the port objects from before instead of port names:
189-
190-
>>> client.connect(out2, 'system:playback_2')
191-
>>> in2.connect('system:capture_2')
192-
193-
Use `jack.Client.get_all_connections()` to find out which other ports are
194-
connected to a given port.
195-
If you own the port, you can also use `jack.OwnPort.connections`.
196-
197-
>>> client.get_all_connections('system:playback_1')
198-
[jack.OwnPort('MyGreatClient:output_1')]
199-
>>> out2.connections
200-
[jack.Port('system:playback_2')]
201-
202-
Of course you can also disconnect ports, there are again several possibilities:
203-
204-
>>> client.disconnect('system:capture_1', 'MyGreatClient:input_1')
205-
>>> client.disconnect(out2, 'system:playback_2')
206-
>>> in2.disconnect() # disconnect all connections with in2
207-
208-
If you don't need your ports anymore, you can un-register them:
209-
210-
>>> in2.unregister()
211-
>>> client.outports.clear() # unregister all audio output ports
212-
213-
Finally, you can de-activate your JACK client and close it:
214-
215-
>>> client.deactivate()
216-
>>> client.close()

‎doc/api.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
API Documentation
2+
=================
3+
4+
.. automodule:: jack
5+
:members:
6+
:undoc-members:

‎doc/contributing.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../CONTRIBUTING.rst

‎doc/examples.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
:orphan:
2-
31
Example Programs
42
================
53

‎doc/index.rst‎

Lines changed: 9 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,17 @@
11
.. include:: ../README.rst
22

3-
.. only:: html
4-
5-
More Examples
6-
-------------
7-
8-
For more examples, have a look at the :doc:`examples`.
3+
----
94

10-
.. include:: ../CONTRIBUTING.rst
5+
.. toctree::
116

12-
API Documentation
13-
-----------------
14-
15-
.. automodule:: jack
16-
:members:
17-
:undoc-members:
7+
installation
8+
usage
9+
examples
10+
api
11+
contributing
12+
version-history
13+
other-modules
1814

1915
.. only:: html
2016

21-
Index
22-
-----
23-
2417
:ref:`genindex`
25-
26-
Version History
27-
---------------
28-
29-
.. include:: ../NEWS.rst
30-
31-
Other Python Modules for JACK
32-
-----------------------------
33-
34-
PyJack
35-
https://sourceforge.net/projects/py-jack/
36-
37-
jacklib from Cadence
38-
https://github.com/falkTX/Cadence/blob/master/src/jacklib.py
39-
40-
jacker
41-
https://github.com/fphammerle/jacker

‎doc/installation.rst‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
Installation
2+
============
3+
4+
.. image:: https://badge.fury.io/py/JACK-Client.svg
5+
:target: https://pypi.org/project/JACK-Client/
6+
7+
You can use ``pip`` to install the ``jack`` module::
8+
9+
python3 -m pip install JACK-Client
10+
11+
Depending on your Python installation (see `Requirements`_ below),
12+
you may have to use ``python`` instead of ``python3``.
13+
If you have installed the module already, you can use the ``--upgrade`` flag to
14+
get the newest release.
15+
16+
To un-install, use::
17+
18+
python3 -m pip uninstall JACK-Client
19+
20+
Requirements
21+
------------
22+
23+
You'll need some software packages in order to install and use the ``jack``
24+
module. Some of those might already be installed on your system and some are
25+
automatically installed when you use the aforementioned ``pip`` command.
26+
27+
Python:
28+
Of course, you'll need Python_. More specifically, you'll need Python 3.
29+
If you don't have Python installed yet, you should get one of the
30+
distributions which already include CFFI and NumPy (and many other useful
31+
things), e.g. Anaconda_ or WinPython_.
32+
33+
pip/setuptools:
34+
Those are needed for the installation of the Python module and its
35+
dependencies. Most systems will have these installed already, but if not,
36+
you should install it with your package manager or you can download and
37+
install ``pip`` and ``setuptools`` as described on the `pip installation`_
38+
page.
39+
If you happen to have ``pip`` but not ``setuptools``, use this command::
40+
41+
python3 -m pip install setuptools
42+
43+
To upgrade to a newer version of an already installed package (including
44+
``pip`` itself), use the ``--upgrade`` flag.
45+
46+
CFFI:
47+
The `C Foreign Function Interface for Python`_ is used to access the C-API
48+
of the JACK library from within Python. It is supported on CPython
49+
and is distributed with PyPy_. It will be automatically installed
50+
when installing the ``JACK-Client`` package with ``pip``.
51+
If you prefer, you can also install it with your package
52+
manager (the package might be called ``python3-cffi`` or similar).
53+
54+
JACK library:
55+
The JACK_ library must be installed on your system (and CFFI must be able
56+
to find it). Again, you should use your package manager to install it.
57+
Make sure you install the JACK daemon (called ``jackd``). This will also
58+
install the JACK library package.
59+
If you don't have a package manager, you can try one of the binary installers
60+
from the `JACK download page`_.
61+
If you prefer, you can of course also download the sources and compile
62+
everything locally.
63+
64+
NumPy (optional):
65+
NumPy_ is only needed if you want to access the input and output buffers in
66+
the process callback as NumPy arrays.
67+
The only place where NumPy is needed is `jack.OwnPort.get_array()`
68+
(and you can use `jack.OwnPort.get_buffer()` as a NumPy-less alternative).
69+
If you need NumPy, you can install it with your package manager or use a
70+
Python distribution that already includes NumPy (see above).
71+
You can also install NumPy with ``pip``, but depending on your platform, this
72+
might require a compiler and several additional libraries::
73+
74+
python3 -m pip install NumPy
75+
76+
.. _JACK: https://jackaudio.org/
77+
.. _NumPy: https://numpy.org/
78+
.. _Python: https://www.python.org/
79+
.. _Anaconda: https://www.anaconda.com/products/individual#Downloads
80+
.. _WinPython: http://winpython.github.io/
81+
.. _C Foreign Function Interface for Python: https://cffi.readthedocs.org/
82+
.. _PyPy: https://www.pypy.org/
83+
.. _JACK download page: https://jackaudio.org/downloads/
84+
.. _pip installation: https://pip.pypa.io/en/latest/installing/

‎doc/other-modules.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Other Python Modules for JACK
2+
=============================
3+
4+
PyJack
5+
https://sourceforge.net/projects/py-jack/
6+
7+
jacklib from Cadence
8+
https://github.com/falkTX/Cadence/blob/master/src/jacklib.py
9+
10+
jacker
11+
https://github.com/fphammerle/jacker

0 commit comments

Comments
 (0)