= pyAculab - Aculab extension for Python =
 * exposes the Aculab API through [http://www.swig.org/ SWIG].
 * contains a [http://en.wikipedia.org/wiki/Model-view-controller model-view-controller] framework layer that integrates call-control, switching and media handling. 
 * contains helper classes for thread-based timers and [http://ibp.de/aculab/apidocs/aculab.sdp.html SDP parsing/generation].
 * supports v5 call drivers/TiNG 1 to v6 call drivers/TiNG 2. This means that the Aculab BRI cards are supported.

pyAculab application code is asynchronous and structured around the classical [http://en.wikipedia.org/wiki/Model-view-controller model-view-controller] pattern.

== Intended audience ==
 * Developers that are familiar with the Aculab API and need a prototyping tool.

== How does it look like? ==

This example shows how to accept a call, wait for the remote disconnect, and then exit:
{{{
#!python
import sys
import logging
import aculab
from aculab.reactor import Reactor
from aculab.callcontrol import Call

class IncomingCallController:
    def ev_incoming_call_det(self, call, model):
        log.debug('%s stream: %d timeslot: %d features: %d',
                  call.name, call.details.stream, call.details.ts,
                  call.details.feature_information)

        call.accept()

    def ev_remote_disconnect(self, call, model):
        call.disconnect()

    def ev_idle(self, call, model):
        raise StopIteration

if __name__ == '__main__':

    aculab.defaultLogging(logging.DEBUG)
    controller = IncomingCallController()

    c = Call(controller)

    Reactor.run()
}}}

In our test setup, a call to this script will result in this output:
{{{
2007-02-19 23:44:14,745 call DEBUG cc-8001 openin()
2007-02-19 23:44:14,747 call DEBUG cc-8001 ev_wait_for_incoming (ignored)
2007-02-19 23:44:42,062 call DEBUG cc-8001 ev_incoming_call_det (call, controller)
2007-02-19 23:44:42,064 call DEBUG cc-8001 stream: 32 timeslot: 1: features: 0
2007-02-19 23:44:42,069 call DEBUG cc-8001 accept()
2007-02-19 23:44:42,842 call DEBUG cc-8001 ev_call_connected (call)
2007-02-19 23:44:49,042 call DEBUG cc-8001 ev_remote_disconnect (controller)
2007-02-19 23:44:49,045 call DEBUG cc-8001 disconnect(0)
2007-02-19 23:44:49,304 call DEBUG cc-8001 ev_idle (call)
2007-02-19 23:44:49,307 call DEBUG cc-8001 release(0)
}}}

You can see all Aculab events with accurate timing information, including events that are not handled: in this case EV_WAIT_FOR_INCOMING

== Prerequisites ==

 * [http://www.aculab.com/ Aculab] drivers from a friendly AIT account near you.
 * [http://www.python.org/ Python], version 2.5 or later.
 * [http://www.swig.org/ SWIG], version 1.3.24 or later.
 * GNU make.
 * GNU patch.

If you have the FAX Group3 Prosody library installed, you will also need the [http://fontconfig.org/wiki/ fontconfig] library. On a Debian system, install {{{libfontconfig1-dev}}}, i.e. do {{{apt-get install libfontconfig1-dev}}}.

=== Operating systems ===

 * Linux
 * Windows. See [wiki:Windows] for build instructions. 

== License ==

The Aculab wrappers are available under the [http://ibp.de/aculab/license.txt Apache License, version 2.0].

== Download ==

 * Source: [[FindFile('aculab', 'pyAculab-([0-9]+).*tar.gz', link)]]
 * Windows Installer: [[FindFile('aculab', 'pyAculab-([0-9]+).*exe', link)]]

== Subversion access ==

Anonymous read-only access to the Subversion repository is allowed, to check out the latest version, do (for example):
{{{
svn checkout http://svn.ibp.de/svn/aculab/trunk aculab
}}}

Or:
{{{
svn checkout http://svn.ibp.de/svn/aculab/trunk/python pyAculab
}}}

If you [http://svn.ibp.de/projects/aculab/register register here], you will get write access to the repository.

== Documentation ==
 
 * [http://svn.ibp.de/aculab/apidocs/aculab.html Package overview] ''This is the recommended starting point''
 * [http://svn.ibp.de/aculab/apidocs/index.html Indices by name, inheritance and package hierarchy]

== More examples ==

 * [source:/trunk/python/callout.py Make (multiple) outgoing calls. Also shows CUG and UUI generation.]
 * [source:/trunk/python/play.py Play multiple files. Also shows how to use a timer.]
 * [source:/trunk/python/sipin.py An incoming SIP call with RTP.]
 * [source:/trunk/python/sipout.py An outgoing SIP call with RTP.]

== Where is the magic? ==

It's [wiki:Magic hidden].

== Testing ==

There is no test suite, but running  [source:/trunk/python/dtmfloop.py dtmfloop.py] exercises a lot of the internal machinery. It:
 * creates two [http://svn.ibp.de/aculab/apidocs/aculab.speech.SpeechChannel.html SpeechChannels]
 * connects them
 * plays '0123456789*#' plus CNG on one channel
 * recognizes the tones on the other channel

All tones should be recognized and the process should exits when it is finished.

The output looks something like this (switching details vary with hardware):

{{{
2008-02-15 23:27:27,307 DEBUG speech sc-8388e78 tx: 48:0, rx: 48:1 card: 0
2008-02-15 23:27:27,307 DEBUG speech sc-8388580 tx: 48:2, rx: 48:3 card: 0
2008-02-15 23:27:27,308 DEBUG switch sc-8388580 48:3 := 48:0
2008-02-15 23:27:27,308 DEBUG switch sc-8388e78 48:1 := 48:2
2008-02-15 23:27:27,309 DEBUG speech sc-8388580 listening for DTMF/Tones with toneset 2
2008-02-15 23:27:27,310 DEBUG speech sc-8388580 record(<open file 'dtmf.al', mode 'wb' at 0xb7c94380>, max_octets=0, max_time=0.000, max_silence=1.000, elimination=0, agc=0, volume=0)
2008-02-15 23:27:27,310 DEBUG speech sc-8388e78 digits(0123456789*#, inter_digit_delay=0, digit_duration=0)
2008-02-15 23:27:27,439 DEBUG speech sc-8388580 recognised tone: 0 (3:1)
2008-02-15 23:27:27,631 DEBUG speech sc-8388580 recognised tone: 1 (0:0)
2008-02-15 23:27:27,823 DEBUG speech sc-8388580 recognised tone: 2 (0:1)
2008-02-15 23:27:28,015 DEBUG speech sc-8388580 recognised tone: 3 (0:2)
2008-02-15 23:27:28,239 DEBUG speech sc-8388580 recognised tone: 4 (1:0)
2008-02-15 23:27:28,431 DEBUG speech sc-8388580 recognised tone: 5 (1:1)
2008-02-15 23:27:28,623 DEBUG speech sc-8388580 recognised tone: 6 (1:2)
2008-02-15 23:27:28,815 DEBUG speech sc-8388580 recognised tone: 7 (2:0)
2008-02-15 23:27:29,039 DEBUG speech sc-8388580 recognised tone: 8 (2:1)
2008-02-15 23:27:29,231 DEBUG speech sc-8388580 recognised tone: 9 (2:2)
2008-02-15 23:27:29,423 DEBUG speech sc-8388580 recognised tone: * (3:0)
2008-02-15 23:27:29,615 DEBUG speech sc-8388580 recognised tone: # (3:2)
2008-02-15 23:27:29,767 DEBUG speech sc-8388e78 digits_done(reason='None')
2008-02-15 23:27:29,767 DEBUG speech sc-8388e78 tone(23, duration=1.000)
2008-02-15 23:27:29,903 DEBUG speech sc-8388580 recognised tone: CNG (4:3)
2008-02-15 23:27:30,831 DEBUG speech sc-8388e78 tone_done(reason='None')
2008-02-15 23:27:30,831 DEBUG speech sc-8388e78 silence(agc=0, speed=0, volume=0)
2008-02-15 23:27:31,855 DEBUG speech sc-8388580 record_done(reason='silence(0.992s)', length=4.760s)
2008-02-15 23:27:31,879 DEBUG speech sc-8388e78 silence_done(reason='None', duration=1.000)
2008-02-15 23:27:31,901 DEBUG switch 48:01 disabled
2008-02-15 23:27:31,902 DEBUG switch 48:03 disabled
}}}

For a complete list of local wiki pages, see TitleIndex.