next up previous contents index
Next: IXD (Integra eXtensible Data) Up: libIntegra: a system for Previous: The Integra project   Contents   Index


Integra modules

The basis of the Integra library is the concept of the Integra module. Integra modules encapsulate a specific piece of message or signal processing functionality. A module could perform a simple task like a numeric addition, or a complex task like emulating a specific synthesiser. In this section, we will outline how Integra modules and module collections are constructed.

Module construction

The minimum requirement for an Integra module is that it must have an interface definition. In addition, it may also have an implementation and module instance data. Of these, only the implementation is software specific.

Module definition

An Integra module definition is data that defines what attributes a module has, and what the characteristics of those attributes are. An Integra attribute is a symbolic name with which a value can be associated. The module definition does not store the actual values of attributes, instead it stores data about the attributes such as their names, descriptions, supported data types, maxima and minima, and default values. Typical module definition data is shown in Table [*].

Table: Integra Oscillator interface definition
Field Value
Name Oscillator
Parent Module
Attributes freq, phase
Attribute Unit Codes 1, 2
Attribute Minima 0, 0
Attribute Maxima inf, 6.2831853071795862
Attribute Defaults 440, 0

The parent field is used to show an inheritance relation. All Integra module definitions could be thought of as class definitions, the members of which are all abstract (lack implementation), or interface definitions. The interface of a given class can inherit the interface of any other class, and supplement this with additional members. This definition hierarchy is the basis of the Integra database (see section [*]).

Module namespace

A module's namespace is derived from its definition. The namespace enables the values of attributes to be set, and module methods to be called by using a symbolic naming scheme. From the user's perspective, this will usually manifest itself as an automatically generated OSC address space. The OSC address space for a Sinus module is shown in table [*]. The 'Sinus' class inherits the 'Oscillator' class interface, which in turn inherits the 'Module' class interface, so the attributes of these inherited classes must be reflected in the Sinus module's namespace. To keep addresses short, class names are omitted from the namespace unless there is a name clash.

Table: Integra Sinus module namespace
OSC address Purpose
/<modulename>/freq <value>
Set the value of the 'freq' attribute
/<modulename>/phase <value>
Set the value of the 'phase' attribute
/<modulename>/active <value>
Set whether or not the module is active

Module implementation

The module implementation is the only software-specific data stored by Integra. It consists of a fragment of computer code, in one or more files, which when run or loaded by a particular piece of software will perform a specific audio or message processing task. In order that module implementations can be used by libIntegra, an implementation protocol must be devised for each software target. This protocol must then supported by the target-specific libIntegra bridge (see figure [*]).

Integra currently provides implementation protocols for Max/MSP and Pure Data along with a growing selection of example module implementations and implementation templates. An eventual aim of Integra is to provide a protocol for constructing module implementations in a range of different software, and to develop a LADSPA/DSSI2 host that wraps plugins in an Integra-compliant manner.

Module instance data

Module instance data consists of the run-time state of all of its variable parameters. This data is stored in memory by the Integra library whilst a module is in use, and can be written to an XML file on demand. This data is stored in the Integra database in the module's instance table. However only one saved state can be associated with each module instance. If the user wishes to record state changes over time, then a separate 'Player' module must be used to store this data.

Module collections

An Integra collection consists of one or more Integra module instances. A collection can also contain other collections. These contained collections encapsulate the functionality of a number of connected Integra modules into a single entity and can be addressed and connected as if they were normal module instances. The facility is provided for collections to optionally expose the input and output parameters of the modules they contain. For example, the collection 'mySinus' might contain a Sinus module, which has the attributes Frequency and Phase, but the collection might only expose the Frequency attribute to the containing collection, whilst setting the Phase to some arbitrary constant value.

Module ports

Modules and collections are connected up to each other using Integra ports. Each port corresponds to an audio or messaging address, which has both a symbolic name and a numeric identifier (port ID). Port symbolic names correspond to a module's attribute names (e.g. 'freq'), and port numbers are derived implicitly from the index of the port in the module's attribute list. In addition to its port numbers, each module has a globally unique symbolic name (e.g. 'sinus1'), and an implicitly determined, globally unique numeric identifier (UID). The Integra library can be used to address any module port using either its symbolic name and attribute name (e.g. '/sinus1/freq'), or using a combination of its UID and port ID. It is an important part of the Integra module construction protocol that port ordering is always consistent. Otherwise a module implementation's port numbering will not correspond to the numbering expected by the Integra library.

From the perspective of the Integra library, database, and XML schema, there is no distinction between audio and control rate ports. This distinction is only made in the implementation. There is also no conceptual distinction between input ports and output ports; a port is just an address that can receive data and connect to other addresses.


For each module or collection, the Integra library stores a list of ports that each output port of a given module is connected to. One-to-many, many-to-one or many-to-many connections can easily be established. It is important to note that for audio connections, the software hosting the modules must support the required routings. This is because the library doesn't currently process audio-rate data.

next up previous contents index
Next: IXD (Integra eXtensible Data) Up: libIntegra: a system for Previous: The Integra project   Contents   Index
Jamie Bullock, Henrik Frisk