pyjack-0.5.2/README

   1 PyJack version 0.x
   2 Original code by Andrew W. Schmeder <andy@a2hd.com>, in2003
   3 Transport support by Il'dar Akhmetgaleev <akhilman at gmail dot com>, in Jan 14 2008
   4 Revision and packaging by falkTX <falktx@gmail.com>, in Feb 2010
   5 Implemented changes by the Clam Team <falktx@gmail.com>, in Mar 2010
   6 More Jack implementations by falkTX <falktx@gmail.com>, in Apr 2010
   7
   8
   9 This is open source software released under the GPL license.
  10 The full text of this license is found in the file 'LICENSE',
  11 included with this source code package.
  12
  13 This software is presently distributed from http://www.a2hd.com.
  14 Please check that site for the latest version.
  15
  16 ------------------------------------------------------------------------
  17 ------------------------------------------------------------------------
  18 Description:
  19
  20   PyJack is a module written in C which exposes the Jack API to Python.
  21 For information about Jack see http://jackit.sourceforge.net.  This
  22 enables a Python program to connect to and interact with pro-audio
  23 applications which use the Jack Audio Server.
  24
  25 ------------------------------------------------------------------------
  26 Purpose:
  27
  28 - To show that it can be done.
  29
  30 - For programmers who want to prototype DSP and sound synthesis
  31 algorithms using Numeric Python and similar tools.  PyJack provides the
  32 means to capture and playback audio.
  33
  34 -  For patchbay applications; A powerful Jack patchbay can be written
  35 in Python using this module.  This is planned for the future.
  36
  37 ------------------------------------------------------------------------
  38 Installation:
  39
  40   This package uses the excellent and simple Python distutils.
  41   Installation is very simple.  It works something like this;
  42
  43 # tar -xzvf pyjack-0.*.tar.gz           (unpack archive)
  44 # cd pyjack-0.*                         (cd to source dir)
  45 # (sudo) python setup.py install        (install...)
  46
  47 ------------------------------------------------------------------------
  48 Demos:
  49
  50   Demos can be found in the "demos" directory
  51
  52 ------------------------------------------------------------------------
  53 Realtime Issues:
  54
  55   Python is known to be relatively slow (compared to C/C++),
  56 and non-realtime due to memory management details.  Because of this,
  57 Python is -NOT- a suitable language for realtime audio processing!
  58 This means that it is unacceptable to place the Python intepreter
  59 "inside" of a Jack client.
  60   PyJack therefore uses a "semi-detached" method.  The PyJack
  61 client consists of two threads; a Jack client thread and a Python
  62 thread.  The Jack client thread is run in realtime context; it never
  63 blocks, it is entirely deterministic, and does not touch any Python
  64 data structures nor the interpreter.  The Jack client thread merely
  65 copies audio data in/out of socket buffers.  On the Python side,
  66 calls to jack.process() copy audio data in/out of the other end of
  67 those sockets providing the connection to Python via Numeric arrays
  68 of floats.  In any case, use of a large buffer size (e.g. 1024 samples)
  69 is recommended.
  70   In order to capture or playback audio without missing a block,
  71 Python must call jack.process() at least once every 500*(N/Sr)
  72 milliseconds.  (N = jack.get_buffer_size(), Sr = jack.get_sample_rate()).
  73 If this rate is not kept up, you may get jack.InputSyncError or
  74 jack.OutputSyncError exceptions thrown by jack.process().
  75   Typically you will want to use the following design for a DSP
  76 prototyping program:
  77
  78   1.  Attach to the jack server (jack.attach)
  79       Create input and output ports (jack.register_port)
  80       Connect inputs and outputs to jack graph (jack.connect)
  81       Activate client (jack.activate)
  82   2.  Preallocate matricies for input and output audio data
  83   3.  Capture X seconds of audio (jack.process)
  84   4.  Process audio using your algorithm
  85       It does not matter how long this takes...
  86   5.  Playback X seconds of audio (jack.process)
  87   6.  Detach from jack server (jack.detach)
  88
  89   See the example code to get started; testtone.py and capture.py.
  90
  91 ------------------------------------------------------------------------
  92 ------------------------------------------------------------------------
  93 ------------------------------------------------------------------------
  94 Module Documentation and Usage Examples:
  95
  96 Example: Importing the module:
  97 >>> import jack
  98 >>> dir(jack)
  99 ['CanMonitor', ... ]
 100 >>> print jack.attach.__doc__
 101 Attach client to the Jack server
 102
 103 ------------------------------------------------------------------------
 104 Exceptions Thrown by the Jack module:
 105
 106   These are called jack.Error, jack.InputSyncError, etc.
 107
 108 jack.Error:
 109   A general exception thrown when things go wrong.  Usually something
 110   bad, like "can't connect to server", or "failed to connect ports"
 111
 112 jack.NotConnectedError:
 113   Thrown when you try to access a jack API function before the client
 114   has been attached.
 115
 116 jack.UsageError:
 117   Thrown when you are misusing the PyJack API.  For example, trying to
 118   call jack.activate() when the client has already been activated.
 119
 120 jack.InputSyncError:
 121 jack.OutputSyncError:
 122   Often the low level jack client thread is not synchronized with the
 123   Python side.  This exception will be thrown to warn you that there a
 124   potential synchronization problem.  jack.OutputSyncError is extremely
 125   uncommon, you should not ever see that error.  jack.InputSyncError is
 126   very common, for example if you have activated the client but do not
 127   start calling jack.process() immediately.
 128
 129 >>> import jack
 130 >>> import time
 131 >>> jack.attach("test")
 132 ... etc
 133 >>> jack.activate()
 134 >>> time.sleep(1)
 135 >>> jack.process(output, input)
 136
 137   Here you will get a InputSyncError, because you have been sleeping
 138   for 1 second, the data in the audio buffer is about 1 second old.
 139   In other words, the input stream has been stopped for 1 second,
 140   holding old data. In spite of getting this error, you _will_ get
 141   the old audio data in your input array.
 142
 143   Say that you want to write a monitoring application in Python; Now,
 144   having a toolkit running along with audio processing in realtime is
 145   nearly impossible (I've tried it; there is just not enough time to
 146   redraw the screen without getting an InputSyncError). Basically what
 147   you will want to do is only call jack.process() a few times per
 148   second (say 5 times per second).  Each time you call jack.process()
 149   it will throw an InputSyncError, but you know that the audio data is
 150   at most 1/5th of a second old; that is probably good enough for a
 151   very simple metering of the input without making the GUI requirements
 152   too extreme.
 153
 154 ------------------------------------------------------------------------
 155 Jack Port Flags:
 156
 157 jack.IsInput
 158 jack.IsOutput
 159 jack.CanMonitor
 160 jack.IsPhysical
 161 jack.IsTerminal
 162
 163   These are bit flags which indicate the properties of Jack ports.  Use
 164   the bitwise operators (| and &) with them;
 165
 166 Example:
 167 >>> print jack.get_port_flags('alsa_pcm:capture_1')
 168 22
 169 >>> print (jack.get_port_flags('alsa_pcm:capture_1') & jack.IsInput) > 0
 170 0
 171 >>> print (jack.get_port_flags('alsa_pcm:capture_1') & jack.IsOutput) > 0
 172 1
 173 >>> print (jack.get_port_flags('alsa_pcm:capture_1') & jack.IsPhysical) > 0
 174 1
 175 >>> print (jack.get_port_flags('alsa_pcm:capture_1') & jack.IsTerminal) > 0
 176 1
 177 >>> print (jack.get_port_flags('alsa_pcm:capture_1') & jack.CanMonitor) > 0
 178 0
 179
 180   When creating ports, you will want to use a bitwise | of the flags;
 181
 182 >>> jack.register_port("input_1", jack.IsInput | jack.CanMonitor)
 183 >>> jack.register_port("input_1", jack.IsOutput | jack.CanMonitor)
 184
 185 ------------------------------------------------------------------------
 186 Function calls in the jack module:
 187
 188 ---
 189 jack.attach(name)
 190   Attach to the jack server using the given client name.
 191   All other function calls in the jack module require that you call
 192   this function first.  (otherwise you will get a NotConnectedError).
 193
 194 >>> jack.attach("foo_client")
 195
 196 ---
 197 jack.detach()
 198   Detach from the jack server
 199
 200 >>> jack.detach()
 201 >>> jack.get_sample_rate()
 202 Traceback (most recent call last):
 203   File "<stdin>", line 1, in ?
 204 jack.NotConnectedError: Jack connection has not yet been established.
 205
 206 ---
 207 jack.register_port(name, flags)
 208   Create a new port for this client with the given flags.
 209   Once a port is created it cannot be 'unregistered'.
 210   (The Jack API does permit this, but the PyJack module does not support it.)
 211
 212 ---
 213 jack.activate()
 214   Enables callbacks to the realtime jack thread.
 215   This must be called before jack.process() is used.
 216   Enabling the realtime thread has minimal CPU overhead.
 217
 218 ---
 219 jack.deactivate()
 220   Disables Jack callbacks to the realtime thread.
 221   Opposite of jack.activate()
 222   jack.process() cannot be used after jack.deactivate() is called,
 223   until jack.activate() is called again.
 224
 225 ---
 226 jack.process()
 227   This function exchanges audio between Python and the realtime jack thread.
 228
 229   It requires two arguments, which are both 2D Numeric Python arrays.
 230   The arrays -must- be of type 'Float'.  The size in the first dimenision
 231   must match the number of inputs or outputs, and the size of the second
 232   dimension must match the buffer size.  See capture.py and testtone.py
 233   for examples of how this works.  Following is a part of the code from
 234   testtone.py.  In this example there is only one input port and one output
 235   port.  input.shape = (1, 1024), output.shape = (1, 144000).
 236   Notice that process will modify entries in the input array.
 237
 238 input = Numeric.zeros((1,N), 'f')    # note the float type here...
 239 output = Numeric.reshape(
 240     Numeric.sin(
 241         2*Numeric.pi*440.0 * (Numeric.arange(0, sec, 1.0/(Sr), 'f')[0:int(Sr*sec)])
 242     ), (1, Sr*sec)).astype('f')
 243
 244 i = 0
 245 while i < output.shape[1] - N:
 246     try:
 247         jack.process(output[:,i:i+N], input)
 248         i += N
 249     except jack.InputSyncError:
 250         pass
 251     except jack.OutputSyncError:
 252         pass
 253
 254 ---
 255 jack.get_ports()
 256   Returns a list of all registered ports in the Jack graph.
 257   The name of a port looks like: "client_name:port_name"
 258
 259 >>> jack.get_ports()
 260 ['alsa_pcm:capture_1', 'alsa_pcm:capture_2', 'alsa_pcm:capture_3', ... ]
 261
 262 ---
 263 jack.get_port_flags()
 264   Returns an integer which is the bitwise-or of all flags for a given port.
 265
 266 >>> jack.get_port_flags('alsa_pcm:playback_6')
 267 21
 268
 269 ---
 270 jack.get_connections()
 271   Returns a list of ports connected to the given port.
 272   If nothing is connected, returns a list of length zero.
 273
 274 >>> jack.get_connections('alsa_pcm:capture_1')
 275 ['foo_client:input_1']
 276
 277 ---
 278 jack.connect(source, destination)
 279   Connect two ports on the Jack graph.
 280   Note that source must have the IsOutput flag, and
 281   destination must have the IsInput flag.
 282   If you want to recieve or send audio, you must
 283   connect your client's inputs/outputs (those
 284   ports registered via jack.register_port()) to
 285   something else which is generating or recieving
 286   audio, e.g. the alsa_pcm ports.
 287   You can connect ports which belong to other clients
 288   as well, e.g. for a patchbay application.
 289
 290   At the time of writing, there is a bug in the Jack
 291   API which causes audio data to be missing from
 292   input buffers if ports are connected before
 293   jack.activate() is called.  Until this is fixed,
 294   please make sure that you call jack.activate()
 295   prior to using jack.connect().
 296
 297 ---
 298 jack.disconnect(source, destination)
 299   Break a connection established by jack.connect().
 300
 301 ---
 302 jack.get_buffer_size()
 303   Returns the current buffer size used by the Jack server.
 304   If this number is small you may have a lot of synchronization problems.
 305
 306 ---
 307 jack.get_sample_rate()
 308   Returns the current sample rate used by the Jack server.
 309
 310 ---
 311 jack.check_events()
 312   Check if any asynchronous event callbacks have been raised since
 313   the last call to jack.check_events().
 314   Use of this function does -NOT- require that you be presently attached
 315   to the Jack server; however the values will not change unless you are!
 316
 317 >>> jack.check_events()
 318 {'graph_ordering': 0, 'shutdown': 0, 'port_registration': 0, 'hangup': 0}
 319
 320 If graph_ordering == 1:
 321   Then a pair of ports somewhere in the jack graph has been connected or
 322 disconnected.
 323
 324 If port_registration == 1:
 325   Then a port has been added or removed from the jack graph.
 326
 327 If shutdown == 1:
 328   Then the Jack server has shutdown; your client is no longer attached.
 329
 330 If hangup == 1:
 331   Then the Jack server decided to kill the PyJack client for some reason;
 332   the client is no longer attached.
 333
 334   Any flag which is raised is immediatly reset to zero when this
 335   function is called.
 336
 337 ------------------------------------------------------------------------
 338
 339