Kai Vehmanen

260799

Table of Contents

1: Preface

2: Development

2.1: Open design

2.2: System vs interface

2.3: Use cases

2.4: Sanity checks

3: Signal flow

4: Control flow

4.1: Passive operation

4.2: Interactive operation

5: Class descriptions

5.1: Core

5.1.1: ECA_PROCESSOR

5.1.2: ECA_SESSION

5.1.3: ECA_CONTROLLER

5.2: General

5.2.1: ECA_CHAINSETUP

5.2.2: ECA_RESOURCES

5.3: Data objects

5.3.1: CHAIN

5.3.2: SAMPLEBUFFER

5.4: Audio input/output

5.4.1: AUDIO_IO_DEVICE

5.5: Misc

5.5.1: DEBUG

---

1: Preface

Notice! This is not the actual class/source code documentation. This page is a collection of design notes and thoughts. I've noticed that by trying to write a good class description (roles, interface, use), you quickly find out about possible desing flaws.

2: Development

2.1: Open design

Although specific use-cases are used for testing design concepts, they are not be considered as development goals.

2.2: System vs interface

System design is kept separate from user interface design and feature implementation.

2.3: Use cases

Use-cases are used extensively when designing the user interface.

2.4: Sanity checks

Sanity checks are done only to prevent crashes. All effects and operators happily accept "insane" parameters. :)

3: Signal flow

4: Control flow

4.1: Passive operation

Another way to do passive processing is to create a ECA_CONTROLLER object and use it to to access and modify the ECA_SESSION object before passing it to ECA_PROCESSOR.

4.2: Interactive operation

ECA_SESSION object can contain many ECA_CHAINSETUP objects, but only one of them can be active. On the other hand it is possible that there are no chainsetups. If this is the case, about the only thing you can do is to add a new chainsetup.

When some chainsetup is activated, it can be edited using the interface provided by ECA_CONTROLLER. Before actual processing can start, the chainsetup must first be connected. Only valid chainsetups (at least one input-output pair connected to the same chain) can be connected.

ECA_CHAINSETUP can be...

inactive

- can't be accessed from ECA_PROCESSOR

activated, invalid

- can be edited

activated, valid

- can be connected

connected

- ready for processing

ECA_PROCESSOR status is one of...

not_ready

- ECA_SESSION object is not ready for processing or ECA_PROCESSOR hasn't been created

running

- processing

stopped

- processing hasn't been started or it has been stopped before completion

finished

- processing has been completed

5: Class descriptions

5.1: Core

ECA_PROCESSOR is the actual processing engine. It is initialized with a pointer to a ECA_SESSION object, which has all information needed at runtime. Processing is started with the exec() member function and after that, ECA_PROCESSOR runs on its own. If the interactive mode is enabled in ECA_SESSION, ECA_PROCESSOR can be controlled using the ECA_CONTROLLER class. It offers a safe way to control ecasound. Another way to communicate with ECA_PROCESSOR is to access the ECA_SESSION object directly.

5.1.2: ECA_SESSION

ECA_SESSION represents the data used by ecasound. A session contains all ECA_CHAINSETUP objects and general runtime settings (iactive-mode, debug-level, etc). Only one ECA_CHAINSETUP can be active at a time. To make it easier to control how threads access ECA_SESSION, only ECA_PROCESSOR and ECA_CONTROLLER classes have direct access to ECA_SESSION data and functions. Other classes can only use const members of ECA_SESSION.

5.1.3: ECA_CONTROLLER

ECA_CONTROLLER represents the public interface offered by ecasound engine. It takes string commands and interprets them. Then it either performs the task itself or passes the command to the engine (ECA_PROCESSOR). It also offers functions for modifying ECA_SESSION data. In some rare cases (likes for instance when quitting ecasound) it throws an exception.

5.2: General

ECA_CHAINSETUP represents a group of CHAINs and info about how they are connected. ECA_CHAINSETUP can be constructed from a COMMAND_LINE object or it can be loaded from a ascii file. It's also possible to save a ECA_CHAINSETUP to a simple ascii file. The syntax is identical to command line syntax.

5.2.2: ECA_RESOURCES

This class is an interface to the ~/.ecasouncrc configuration file.

5.3: Data objects

A CHAIN represents a single signal flow abstraction. Every CHAIN has one slot for an audio input device and one slot for output. Because these device objects are unique and can be assigned to multiple chains, id numbers are used to refer to the actual device objects. In addition, CHAIN has a name, a SAMPLE_BUFFER object and a vector of CHAIN_OPERATORs which operate on the sample data.

5.3.2: SAMPLEBUFFER

Basic unit for representing sample data. The data type used to represent a single sample, value range, channel count, sampling rate and system endianess are all specified in "samplebuffer.h".

5.4: Audio input/output

AUDIO_IO_DEVICE is a virtual base class for all audio io-devices. Audio devices can be opened in the following modes: read, write or read_write. Input and output routines take pointers to SAMPLE_BUFFER objects as their arguments. All devices are either non-realtime (normal files) or realtime (soundcards). Realtime means that once device is started, data input/output doesn't depend on calls to AUDIO_IO_DEVICE object. With non-realtime devices, input and output is done only when requested. Due to performance issues, much of the responsibility is given to the user of these classes. It's not impossible to write to an object opened for reading (probably with disastrous results).

5.5: Misc

Virtual interface class for the debugging subsystem. Ecasound engine sends all debug messages to this class. The actual implementation of this class can be done in many ways. For example in the console mode version of ecasound, TEXTDEBUG class is used to implement the DEBUG interface. It sends all messages that have a suitable debug level to the standard output stream. On the other hand, in qtecasound DEBUG is implemented using a Qt widget.