Getting started

• Find out about the philosophy behind Kamaelia
  
• Setting up your environment for development
• Start with the examples in the cookbook
• Learn the fundamentals - get to understand Axon
  
• Find out how to make your own components
• Reference the full set of components
• Understand the full system

Axon - underpinning Kamaelia

Axon is at the heart of Kamaelia - it provides the underlying system implementing components that can execute concurrently. Axon can be downloaded used independently of Kamaelia.

• the mini-axon tutorial - understand Axon fast by building it yourself!
  
• a document about a notation
  
• Full reference documentation
  

Kamaelia - components to build things from!

Kamaelia is the really rather extensive library of components that is growing ontop of Axon.

• Cookbook of examples
• How to write your own components
• Full component reference documentation

Here is a quick overview of some of the most interesting or useful faciliies you can find in Kamaelia. If you are new to Kamaelia you may find this a more useful starting point than the reference documentation:

• Base Modules - Exceptions, IPC, etc.
• Internet - Components for implementing Servers, Clients, Multicast, UDP, etc.
• Protocols - HTTP, bittorrent, echo, Simple reliable multicast, RTP etc.
• Multimedia facilities - Audio and Video
• Utility components - Common tasks including console I/O, Data Filtering, Marshalling

Other stuff:

Kamaelia.Support contains general code (not components) to support components in Kamaelia. This includes code for finding out what is in the repository; support functions for the DVB components etc.

Kamaelia.Experimental contains various random components that we have found useful and are being used in places, but we're not really sure about whether they are the right way of doing things. They might end up eventually in Kamaelia, but there is no guarantee they'll even remotely resemble what is there now!

-- Matt, April 2007
--------------------------

Older legacy documentation now follows. This will hopefully be superceeded by new documentation above shortly as it is getting a little out of date:

Multimedia Modules

Kamaelia.
|-- AOPlayer.py deprecated
|-- vorbisDecodeComponent.py
`-- oggFilePlayComponent.py deprecated

These three files are all related to the same purpose - playback of audio, and also decoding ogg vorbis. There are some restrictions on some of these, and there is a recommendation on which ones to use. Each of these requires a set of libraries - these are covered below.

AOPlayer.py is deprecated, the actual component has moved location, and you really ought not to use this at the moment. This may change at some point in time.

• Requires libao, and the pyao python bindings.

oggFilePlayComponent.py is the oldest piece of code that can be used for decode and playback. It uses the official xiph python bindings to decode ogg vorbis. On the surface this is useful and if all you want to do is decode audio from a file, this does work.

• There is a key restriction - it MUST come from a file object that you have opened. It can't be something that looks like a file, it must be a file. The reason for this is internally the xiph bindings dive into the file object supplied, pull out the C filehandle and pass that over to libvorbisfile.
This imposes some awkward restrictions on your code. This does also mean that the operation of your codebecomes subserviant to the library, rather than the library subserviant to your code.
• Requires the following libraries: libao, libogg, libvorbis, libvorbisfile
• Requires the following python bindings: pyogg, pyvorbis, pyao

This file contains the following components:

• oggPlayer - legacy component - you used to be able to choose between AOPlayer and
• PlayerComponent - This is an abstract class that provides the main functionality of a player. Is is overridden by client subclasses. Subclasses are only expect to override the write method. The key method in the payer component is a play generator. Nastily, this generator calls VorbisFile to enable file reading, unpacking of ogg and decode.
Current concrete subclasses:
• AOPlayer - This simply provides a write method to send audio to a libao audio device.

It's worth noting that the execution here is pretty ugly, and it was the motivation for writing the next file. However, if all you want is to use libvorbisfile, oggFilePlayComponent.py can be useful.

vorbisDecodeComponent.py was written to overcome the limitations metioned above. Specifically this provides 2 components - one that will accept ogg vorbis data on an inbox and provide back raw decoded audio on its outbox, and another that takes audio on its inbox and plays the audio. This provides much cleaner separation. The testing spike included shows how to use a file reading component in conjuction with these two components to provide a file reading/decode chain.

• The two components provided are:
• VorbisDecode - takes ogg vorbis encoded audio from its inbox and provides raw decoded audio on its outbox.
  Important note: This is currently ogg vorbis - as you would read from a file, NOT just vorbis encoded data.
• AOAudioPlaybackAdaptor - takes raw audio recieved on its inbox and sends it to the audio device. Currently this may well be a blocking operation. How to do this in a non-blocking manner is under investigation. If it recieves a producerFinished message on its control inbox, this component exits.

These components rely on the following libraries being installed:

• libogg, libao, libvorbis, libvorbissimple

The python bindings required are:

• The python bindings supplied with libvorbissimple
• Pyrex is therefore also required.

RTP Related Modules

Kamaelia.
|-- bitfieldrec.py
|-- NullPayloadPreFramer.py
|-- NullPayloadRTP.py
|-- RTCPHeader.py
|-- RTPHeader.py
|-- RtpPacker.py

......

• bitfieldrec.py - Module containing utility functions to allow structures with arbitrary structures for bitstreams/bitfields. Currently only supports packing. Does not support unpacking (yet).Bit Field Record Support. Usage:
  1. subclass bfrec
  2. Define a class var "fields"
  3. The value for this field should be a list of "field"s, created by calling the static method field.mkList. This takes a list of tuples, one tuple per field. (fieldname, bitwidth, None or list)
• class field(str)
• staticmethod mkList(fieldDefs)
• fieldDefs = seq of (name, size,extra)
• class bfrec(AxonObject)
• __init__(self, **args):
• structureSize(self)
• pack(self)
• serialiseable(convert,aField) - Returns an iterable collection of values. (eg list) Either an existing one, or puts scalar/singleton values into a list. Doing this removes a special case.
• Algorithm:
• This actually does need documenting properly. The algorithm was designed using test first approaches, and so is pretty solid, but documenting it would be a good idea. If only because it's actually quite nice :)
• NullPayloadPreFramer.py - ....
• This Null payload also assumes constant bit rate load.

Subcomponents functionality:

• FileControl: - Only if RFA internal - isn't
• FileReader - only if internal - isn't
• FileSelector - only if internal - isn't
• Format Decoding
• DataFramaing
• Command Interpreter (Likely to be component core code)

-----------------------------

• NullPayloadRTP.py ......
• RTCPHeader.py ......
• RTPHeader.py ......
• RtpPacker.py ......

MIME & Disk Related modules

Kamaelia.
|-- ReadFileAdaptor.py
|-- MimeRequestComponent.py
|-- SampleMIMERequest.txt
|-- SimpleServerComponent.py
|-- requestLine.py

......

Testing Modules

Kamaelia.
|-- runTests.sh
|-- FortuneCookie_InternetHandlingTests.py
|-- test
| |-- SynchronousLinks_SystemTest.py
| |-- debug.conf
| |-- test.log
| |-- test_ConsoleEcho.py
| |-- test_InternetConnection.py
| |-- test_MimeRequestComponent.py
| |-- test_NullPayloadRTP.py
| |-- test_RtpPacker.py
| |-- test_Selector.py
| `-- test_requestLine.py

......

Experimentation Modules

|-- Sketch
| |-- AO_TEST.py
| |-- DONE.list
| |-- DataSteps.txt
| |-- EchoCheckerProtocolComponent.py
| |-- Forking.py
| |-- PygameTest.py
| |-- TODO.list
| |-- oggFilePlayComponent-refactor.py
| |-- oggPlayComponent.py
| |-- rgrailspuds.txt
| |-- run.log
| |-- simple_decoder.py
| `-- test.py

......

Support Files

|-- Makefile
|-- ComponentClasses.py
|-- SampleTemplateComponent.py
|-- debug.conf
|-- makeDocs.sh
|-- afortune.pl
|-- Support/ - various support files. Wav Audio comes from the OpenOffice.org suite.
|-- doc/ - Autogenerated documentation
|-- docs/ - More autogenerated docs

......