April 2024 - This site, and Kamaelia are being updated. There is significant work needed, and PRs are welcome.
Please note:The documentation
here is lagging, quite badly at the moment, behind the bulk of Kamaelia,
which is where all the interesting effort is going right now. Whilst
everything you see here should largely still be valid, be aware that
this really needs updating. We hope to rectify this ASAP. Good
documenters very welcome!
Kamaelia's modules divide into 2 main sections:
A core subsystem of modules which provide the
main concurrency support
- The core subsystem is suitable for use independently of Kamaelia
itself, and is available as a separate download.
Modules for Kamaelia itself.
This document is the starting point for Kamaelia itself.
This file provides an overview of the current Kamaelia files, what
they are and where appropriate, how they work. This is designed to be a
living document, but not designed as raw API documentation. (There are
better ways of building API documentation) Essentially the purpose of
this documentis to act as "the next layer up" the documentation layers -
stating how and why the different parts are joined together.
Multimedia
Modules
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.pyis
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.
- 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 withlibvorbissimple
- Pyrex is therefore also required.
RTP
Related Modules
......
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
......
Testing
Modules
......
Experimentation
Modules
......
Support
Files
......
