|
1 | 1 | JACK Audio Connection Kit (JACK) Client for Python
|
2 | 2 | ==================================================
|
3 | 3 |
|
4 |
| -This Python module provides bindings for the JACK_ library. |
| 4 | +This Python module (named ``jack``) provides bindings for the JACK_ library. |
5 | 5 |
|
6 | 6 | Documentation:
|
7 | 7 | https://jackclient-python.readthedocs.io/
|
8 | 8 |
|
9 |
| -Code: |
| 9 | +Source code and issue tracker: |
10 | 10 | https://github.com/spatialaudio/jackclient-python/
|
11 | 11 |
|
12 | 12 | License:
|
13 | 13 | MIT -- see the file ``LICENSE`` for details.
|
14 | 14 |
|
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 |
| - |
71 | 15 | .. _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() |
0 commit comments