1
:editor: -*- mode: fundamental; tab-width: 4; indent-tabs-mode: nil -*-
3
:syntax: loosely follows restructured text, http://docutils.sourceforge.net/rst.html
6
===========================
7
Ecasound Programmer's Guide
8
===========================
10
.. #################################################################
11
.. #################################################################
18
This document describes how Ecasound and the related libraries
19
work, how to use them, how to extend and add features and other
20
similar issues. Before reading this document, you should first take a
21
look at other available documentation (especially
22
Ecasound Users's Guide).
24
If not otherwise specified, all documentation refers to the latest
27
.. #################################################################
28
.. #################################################################
33
Hmm, why doesn't this work...?
37
| 28.03.2005 - Added section about "Source code markup", update the
38
| "Design principles" section.
39
| 13.03.2005 - Converted from LaTeX to ascii.
40
| 23.10.2004 - Added section "EIAM commands" that covers adding
42
| 18.11.2003 - Typo fixes. Updated documentation to reflect the new
43
| naming convention (ecasound refers to the binary,
44
| Ecasound refers to the whole package).
45
| 07.11.2002 - Added documentation for NetECI.
46
| 25.10.2002 - Added "Checklist for Audio Object Implementations".
47
| 17.10.2002 - Added a warning against direct use of libecasound
48
| and libkvutils. Using ECI is from now on the
49
| preferred way of using ecasound as a development
50
| platform. Rewrote the "Versioning" section.
51
| 02.10.2002 - Added the "Protocols and Interfaces" chapter.
52
| 29.04.2002 - Added chapter about "Unit Tests".
53
| 28.04.2002 - Revised namespace policy (see chapter
54
| on namespaces), replaced references to
55
| obsolete ECA_DEBUG with a description
56
| of the new ECA_LOGGER subsystem.
57
| 27.02.2002 - Rewrote the "Control flows" chapter according
58
| to the structural changes made in 2.1dev8. Added
59
| a "References" section.
60
| 31.01.2002 - Reorganization of document structure. New chapter
61
| about "Library organization".
62
| 19.12.2001 - Added chapter about include hierarchies.
63
| 28.10.2001 - Lots of changes to the "Object maps" chapter.
64
| 21.10.2001 - Added this history section.
66
.. #################################################################
67
.. #################################################################
69
General programming guidelines
70
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72
Design and programming principles
73
=================================
75
The following sections describe some of the key design
76
principles that have been guiding Ecasound development.
78
Open and generic design
79
-----------------------
81
Over the years Ecasound's core design has been revised many times.
82
The aim has been to keep the core flexible enough, so it can
83
be easily adapted to new use cases.
88
Ecasound is written in C++ (as specified in 1997 ANSI/ISO C++ standard).
89
Common object-oriented design practices should be utilized. At same time
90
overuse of object-orientation should be avoided. Object-orientation is
91
a very effective design method, but not the only one. Sometimes other
92
approaches work better.
97
This design principle deserves to be mentioned separately. Whenever
98
possible, the actual data representation and implementation details
99
should always be hidden. This allows to make local implementation
100
changes without affecting other parts of the code base. It cannot
101
be emphasized enough how important this goal is for large software
102
projects like Ecasound.
107
When writing a new routine, in addition to the actual code,
108
also routine's behaviour should be described as accurately as
109
possible using preconditions and postconditions to describe
110
the external side-effects (how it changes the object state, what
111
is the relation between arguments and return values).
113
The preconditions should specify all requirements and
114
assumptions related to routine's inputs. If the caller violates
115
this specification, routine is not responsible for the error.
117
The postconditions should specify what statements hold true
118
when routine has been executed. This information helps the
119
caller to better understand how the routine works and
120
to identify implementation bugs.
122
Ideally, these conditions prove that the routine works
123
correctly. Writing a complete description of a routine can be
124
difficult, but the benefits of this approach should be clear.
125
When you call a well-defined routine, a) you know what
126
parameter values it accepts, b) you know what it does and c) if
127
errors occur, it's easier to pinpoint the faulty routine.
129
In practice describing routines is done by combining verbose
130
comments and defining pre/postconditions. As C++ doesn't directly
131
support pre/postconditions, the DEFINITION_BY_CONTRACT and DBC tools
132
provided by libkvutils are used.
137
A clear distinction should be made between routines that
138
have side-effects (=methods, processors, modifiers; routines that
139
change object's state) and const routines (=functions, observers).
141
To make monitoring side effects easier, all Ecasound classes
142
should be const-correct. A object is const-correct if a function
143
taking only a single argument that is a const reference to that object
144
is not able, without explicit casting, to obtain a non-const
145
reference to that same object (or a portion thereof) from within
151
Sanity checks are done only to prevent crashes. All effects
152
and operators should accept also "insane" parameters. For example,
153
the amplifier effect accepts -100.0% as the gain value. This of course
154
results in inverted sample data, which is a useful outcome.
155
As Ecasound is supposed to be a tool for creative work and
156
experimenting, the decisions on which parameters are useful
157
for audio processing should not be made in source code.
162
Two specific things worth mentioning: First, the standard UNIX-style
163
error handling, where functions performing actions return an integer
164
value, is not used in Ecasound. As described in the above section
165
Routine side effects, all routines are either modifiers or
166
observers, not both. So when using Ecasound APIs, you first perform an
167
action (modifying function), and then afterwards check what happened
168
(using an observer function).
173
C++ exceptions are used in Ecasound. Exception based error
174
handling has its problems, but in some cases it is clearly the best
175
option. Exceptions are most useful in situations where
176
controlled error recovery is very difficult, and in situations
177
where errors occurs only very rarely. This allows callers to
178
avoid constantly checking returns values for functions that
179
in normal use never fail. Another special case is handling critical
180
errors that occur in class contructors.
182
Using exceptions for anything other than pure error handling
183
is to be avoided at all cost. And when exceptions are used,
184
their use must be specified in function prototypes. This is important,
185
as clients need to know what exceptions can be thrown. C++
186
unfortunately doesn't require strict exception prototypes, so
187
this issue requires extra care.
189
A list of specific cases where exceptions are used follows:
192
This method is used for initializing external connections (opening
193
files or devices, loading shared libraries, opening IPC connections).
194
It's impossible to know in advance what might happen. In many cases it
195
is also useful to get more verbose information about the problem
196
that caused open() to fail. Throwing an exception is an excellent way
199
ECA_CHAINSETUP - enable()
202
ECA_CHAINSETUP - load_from_file, save() and save_to_file
205
ECA_SESSION - constructor
208
Coding style, naming conventions and source code markup
209
=======================================================
211
This section describes some of the conventions used in
212
Ecasound development. As a general rule, one should
213
adapt to whatever style and conventions used in
214
already existing code.
216
Variable and type naming
217
------------------------
219
Variable names are all lower case and words are separated with
220
underscores (int very_long_variable_name_with_underscores). Class data
221
members are marked with "_rep" postfix. Data members which are
222
pointers are marked with "_repp". Index-style short variable names
223
(n, m, etc.) are only used in local scopes. Enum types
224
have capitalized names (Some_enum).
226
Use of macro processing should be avoided, but when necessary,
227
macro names should be capitalized.
232
libecasound, ecasound, ecatools, libkvutils
233
Class names are all in upper case and words separated with underscores
234
(class ECA_CONTROL_BASE). This a standard style in Eiffel programming.
236
libqtecasound, qtecasound, ecawave
237
Qt-style is used when naming classes (class QELevelMeter), otherwise
243
Some classes are divided into public and private parts. This is
244
done to make it easier to maintain binary-level compatibility
245
between library versions, and to get rid of header file
248
Private classes have a "_impl" postfix in their name. They
249
are usually stored into separate files which also use the
252
For instance the ECA_ENGINE class (eca-engine.h) has
253
a private class ECA_ENGINE_impl (eca-engine_impl.h).
254
Access to ECA_ENGINE_impl is only allowed to ECA_ENGINE
255
member functions. In addition, the private header file
256
(eca-engine_impl.h) is only included from the ECA_ENGINE
257
implementation file (eca-engine.cpp). This allows us to
258
add new data members to ECA_ENGINE_impl without breaking
259
the binary interface.
264
Unit tests are used for verifying that modules work as intended.
265
A test for component, with a public interface defined in
266
"prefix-component.h", should located in
267
"prefix-component_test.h". The test itself should implement
268
the ECA_TEST_CASE interface. In addition, generic test cases
269
should be added to ECA_TEST_REPOSITORY - see
270
"libecasound/eca-test-repository.cpp".
275
In addition to the Javadoc-style source code documentation (see
276
'Documentation style' section), inline commentary markup is used
277
to document important code segments. Use of common markup notation
278
is preferred (for example it is nice to be able to grep for a list
279
of open items in certain part of the codebase):
281
- Known bugs, unhandled cases, and missing features should
282
be marked with "FIXME: description" comments.
284
- Explanatory notes that help to understand the code
285
should be marked with "NOTE: description".
287
Physical level organization
288
===========================
290
Ecasound libraries and applications are divided into distribution
291
packages, directories and file groups.
296
Include statements that are not stricly necessary should be dropped!
297
Not only do they cause unwanted dependencies, they also create more
298
work for the compiler (Ecasound already takes painfully long to
299
compile). Some rules to follow:
301
- In header files, no extra header files should be defined.
302
For instance in many cases it's enough to state that
303
object SOME_TYPE is a class without need for the full
304
implementation; so instead of "\#include "sometype.h", use
307
- For modules with separate implementation and header files,
308
dependencies to other modules need not be
311
- Direct dependencies to outside modules must always
312
be mentioned directly. It's easy to unknowingly include
313
a required header file via some other header file. This
314
should be avoided as it hides real dependencies.
316
- When including headers for more special services, it's
317
good to add a comment why this header file is needed.
319
Distribution packages
320
---------------------
322
As an example, Ecasound and Ecawave are distributed as separate
323
packages. This decision has been made because a) they are clearly
324
independent, b) they have different external dependencies, and c)
325
they address different target uses.
330
It's convenient to organize larger sets of source code into separate
331
directories. For instance libecasound and ecatools components of
332
the Ecasound package are located in separate directories.
337
Although files are divided in directories and subdirectories,
338
there's still a need to logically group a set of source files based
339
on their use and role in the overall design. As the use of C++
340
namespaces is very limited in Ecasound (to avoid portability
341
problems), filename prefixes are used for grouping files. Here's
342
a short list of commonly used prefixes.
345
Audio device and file input/output.
347
Audio effects and other DSP-related code.
353
MIDI input/output devices, handlers and controller code.
355
Oscillator and other controller sources.
357
Generic prefix for files utilizing both Qt and Ecasound libraries.
358
samplebuffer*.{cpp,h}
359
Routines and helper functions for processing audio data buffers.
361
You should note that these are just recommendations - there are no
362
strict rules on how files should be named.
367
The preferred way to access C++ standard library functions is
368
to use explicit namespace selectors ("std::string") in public
369
headers files, and "using declarations" in the implementation
370
parts ("using std::string"). It's also possible to import the
371
whole std namespace ("using namespace std;") in the beginning
372
of an implementation file (but never in headers!).
377
Javadoc-style class documentation is the preferred style.
378
Class members can be documented either when they are declared (header
379
files), or when they are defined. Especially when specifying
380
complicated interfaces, it's better to put documentation in the
381
definition files. This way the header files remain compact and serve
382
better as a reference.
384
Here's a few general documentation guide lines:
387
"Writes samples to memory." instead of "Write samples to memory."
388
Sentences start with a verb
389
"Writes samples to memory." instead of "Samples are written to memory."
391
"Get controllers connected to this effect." instead of "Get controllers connected to the effect.
396
All Ecasound releases have a distinct version number. The
397
version number syntax is x.y[.z][-extraT], where x and
398
y are the major and minor numbers, and z is an optional
399
revision number. To test major changes, separate -preX or
400
-rcX versions can be distributed before the official release.
402
In addition, all Ecasound libraries have a separate interface
403
version. The libtool-style version:revision:age versioning
404
is used. See the libtool documentation for details.
406
One important thing to note is that the library interface version
407
numbers are tied to the source-code level interfaces, not the binary
408
interfaces. Because binary interfaces are not explicitly versioned,
409
applications should always statically link against the Ecasound
410
libraries. Also, any private source-code interfaces, ie. header
411
files with a "_impl.h" postfix, are not part of the versioned
412
public interface. Applications should not rely on these interfaces!
414
All changes in the public interfaces are documented in library
415
specific ChangeLog files. These files are usually located in the
416
top-level source directory of the versioned library.
418
One thing to note is that Ecasound's versioning practises have
419
changed quite a few times during the project's history. The
420
rules described above only apply to Ecasound 2.2.0 and newer
423
.. #################################################################
424
.. #################################################################
432
Here's a few common use cases how Ecasound can be used.
434
Simple non-interactive processing
435
---------------------------------
437
One input is processed and then written to one output. This includes effect
438
processing, normal sample playback, format conversions, etc.
443
Multiple inputs are mixed into one output.
445
Real-Time effect processing
446
---------------------------
448
There's at least one real-time input and one real-time output.
449
Signal is sampled from the real-time input, processed and
450
written to the real-time output.
455
One real-time input is processed and written to one or
461
The most common situation is that there are two separate
462
chains. First one consists of real-time input routed to a
463
non-real-time output. This is the recording chain. The
464
other one is the monitor chain and it consists of one or
465
more non-real-time inputs routed to a real-time output.
466
You could also route your real-time input to the monitoring
467
chain, but this is not recommended because of severe
468
timing problems. To synchronize these two separate chains,
469
Ecasound uses a special multitrack mode (which should be
470
enabled automatically).
472
Recycling a signal through external devices
473
-------------------------------------------
475
Just like multirack recording. The only difference is
476
that real-time input and output are externally
482
Basic audio flow inside an Ecasound chainsetup is as follows: Audio
483
data is routed from input audio objects to a group of chains. In
484
the chains audio data is processed using chain operators. After
485
processing data is routed to output objects.
487
Using internal loop devices, it's also possible to route signals
488
from one chain to another. Looping causes extra latency of one
491
Routing of signals is based on the ability to assign inputs and
492
outputs to multiple chains. Assigning an input object to multiple
493
chains divides the audio signal generating multiple copies of
494
the original input data. Similarly with an output object, data from
495
multiple chains is mixed together to one output object.
500
Basic audio flow inside an Ecasound chainsetup is as follows: Audio
501
data is routed from input audio objects to a group of chains. In
502
the chains audio data is processed using chain operators. After
503
processing data is routed to output objects.
505
Using internal loop devices, it's also possible to route signals
506
from one chain to another. Looping causes extra latency of one
509
Routing of signals is based on the ability to assign inputs and
510
outputs to multiple chains. Assigning an input object to multiple
511
chains divides the audio signal generating multiple copies of
512
the original input data. Similarly with an output object, data from
513
multiple chains is mixed together to one output object.
518
When Ecasound is run in batch mode, the program flow is simple.
519
To store the session data, a ECA_SESSION object is first
520
created. The created object is then passed as an argument for
521
ECA_CONTROL class constructor.
523
All required configuration of inputs, outputs and chain
524
operators is done using the services provided by ECA_CONTROL.
525
Once a valid chainsetup is ready for processing, batch
526
operation is initiated by issuing ECA_CONTROL::run(). This
527
function will block until processing is finished.
529
Interactive operation
530
---------------------
532
Interactive operation is similar to batch operation. The
533
important difference is that processing is started with
534
ECA_CONTROL::start(). Unlike run(), start() does not
535
block the calling thread. This makes it possible to
536
continue using the ECA_CONTROL interface while engine
537
is running in the background.
539
Two important concepts to understand when
540
working with ECA_CONTROL are the selected
541
and connected chainsetups. ECA_CONTROL allows
542
working with multiple chainsetups, but only one
543
of them can be edited at a time, and similarly
544
only one at a time can be connected to the
545
processing engine. For instance if you add a new
546
input object with add_audio_input(), it is
547
added to the selected chainsetup. Similarly when
548
you issue start(), the connected chainsetup is
551
.. #################################################################
552
.. #################################################################
557
The primary source for class documentation is header files.
558
A browsable version of header documentation is at
559
http://www.eca.cx/ecasound/Documentation
560
Anyway, let's look at the some central classes.
562
Interfaces for external use
563
===========================
565
The following classes of libecasound are designed as
566
primary interfaces for external use. The approach
567
is based on the Facade (GoF185) design pattern. The primary
568
goals are concentrating functionality, and maintaining
569
a higher level of interface stability.
571
ECA_CONTROL - eca-control.h
572
---------------------------
574
ECA_CONTROL represents the whole public interface offered by
575
libecasound. The primary purpose of ECA_CONTROL is to offer a
576
consistent, straightforward interface for controlling Ecasound.
577
The interface is also designed to be more stable than other
578
parts of the library.
580
On important part of ECA_CONTROL is the functionality for
581
interpreting EOS (Ecasound Option Syntax) and EAIM (Ecasound
582
Interactive Mode) commands.
584
ECA_CONTROL_INTERFACE - eca-control-interface.h
585
-----------------------------------------------
587
C++ implementation of the Ecasound Control Interface (ECI) API. See
588
section "Ecasound Control Interface" for more information.
593
This section introduces the core classes, which define the
594
central data types and are responsible for the main program
597
AUDIO_IO_PROXY_SERVER - audioio-proxy-server.h
598
----------------------------------------------
600
Implements a audio input/output subsystem that adds
601
a second layer of buffering between the main processing
602
engine and non-real-time audio input and output objects.
604
Double buffering is needed to guarantee a real-time constrained
605
data stream even when dealing with non-real-time objects like
611
Class representing one abstract audio signal chain. CHAIN
612
objects consist of chain operators, controllers and their
615
ECA_CHAINSETUP - eca-chainsetup.h
616
---------------------------------
618
ECA_CHAINSETUP is the central class for storing user-visible
619
objects. All inputs, output, chain operator and controller
620
objects belonging to one logical setup are attributes of on
621
ECA_CHAINSETUP object.
623
ECA_ENGINE - eca-engine.h
624
-------------------------
626
ECA_ENGINE is the actual processing engine. It is initialized with
627
a pointer to a ECA_CHAINSETUP object, which has all information
628
needed at runtime. In other words ECA_ENGINE is used to execute
629
the chainsetup. You could say ECA_ENGINE renders the final product
630
according to instruction given in ECA_CHAINSETUP.
632
Processing is started with the exec() member function and
633
after that, ECA_ENGINE runs on its own. If 'batch_mode'
634
is selected (parameter to exec()), one started ECA_ENGINE will
635
run until a 'finished' condition is met and then exit
636
automatically. Finished means that we have read all available data
637
from input sources. Of course if some input has infinite length
638
(soundcards for example), processing will never finish. To get
639
around this limitation, it's possible to set the processing
640
length (see ECA_CONTROL_OBJECTS::set_chainsetup_processing_length_in_seconds()).
642
If batch mode is not enabled, engine will just perform
643
the init phase and starts waiting for further instructions.
644
These instructions can be send to the engine using
645
the ECA_ENGINE::command() member function.
647
ECA_ENGINE has the following states:
650
ECA_SESSION object is not ready for processing or
651
ECA_ENGINE hasn't been created
655
processing hasn't been started or it has been stopped
658
processing has been completed
660
an error has occured during prosessing
662
ECA_SESSION - eca-session.h
663
---------------------------
665
ECA_SESSION is an abtraction used to represents a group of
666
chainsetups. At any time, only one chainsetup object at a time
667
can be active (connected). For modification, one chainsetup
668
can be set as 'selected'. This means that all configuration
669
operations are targeted to the selected chainsetup.
671
The only public access to ECA_SESSION objects is
672
through ECA_CONTROL objects.
674
MIDI_SERVER - midi-server.h
675
---------------------------
677
Engine that handles all MIDI input and output.
679
SAMPLEBUFFER - samplebuffer.h
680
-----------------------------
682
Basic unit for representing blocks of sample data. The data type used
683
to represent single samples, valid value ranges, channel count and system
684
endianess are all specified in "samplebuffer.h" and "sample_specs.h".
686
Feature and capability interface classes
687
========================================
689
Many libecasound classes have similar attribute sets and capabilities.
690
To make use of these shared features, most common features have their
691
own virtual base classes. All objects that have a particular feature,
692
inherit the same virtual base class. This makes object grouping
693
and management easier and less error prone.
695
DYNAMIC_PARAMETERS<T> - dynamic-parameters.h
696
--------------------------------------------
698
Implemented by all classes that provide a set of generic parameters
699
of type T. Parameter can be observed and modified, and they
700
usually are identiefied by a unique name and a more verbose
701
description. Number of parameters can vary dynamically. Other
702
objects can access these parameters without detailed knowledge of
705
ECA_AUDIO_FORMAT - eca-audio-format.h
706
-------------------------------------
708
Implemented by all classes that an audio format attribute
709
set that can be observed and modified.
711
ECA_AUDIO_POSITION - eca-audio-position.h
712
-----------------------------------------
714
Implemented by all classes that need to maintain current audio
717
ECA_SAMPLERATE_AWARE - eca-samplerate-aware.h
718
---------------------------------------------
720
Implemented by all classes that need knowledge of current
723
MIDI_CLIENT - midi-client.h
724
---------------------------
726
Implemented b all classes that require a connection to
727
an instance of MIDI_SERVER.
732
Object interfaces define the behaviour for common objects used
733
by libecasound. The core classes rarely operate on specific
734
object types, but instead use object interfaces (abstract
735
interfaces). Object interfaces are usually abstract C++ classes
736
(instances of these classes cannot be created as some of functions
737
don't yet have a concreate implementation, ie. they pure virtual
743
Virtual base class for all audio I/O objects. Different types
744
of audio objects include files, audio devices, sound
745
producing program modules, audio server clients, and so on.
747
More specialized interface classesa are AUDIO_IO_DEVICE (for
748
real-time audio objects) and AUDIO_IO_BUFFERED (for POSIX-style
749
buffered i/o). There's also a special AUDIO_IO_MANAGER
750
interface for managing multiple audio objects of same
751
type inside one chainsetup.
753
CHAIN_OPERATOR - eca-chainop.h
754
------------------------------
756
Virtual base class for chain operators.
758
CONTROLLER_SOURCE - ctrl-source.h
759
---------------------------------
761
Virtual Base class for all controller sources.
766
Virtual base for objects capable of reading and writing
769
MIDI_HANDLER - midi-server.h
770
----------------------------
772
Virtual base class for objects capable of receiving
773
and processing MIDI data.
775
Object interface implementations - plugins
776
==========================================
778
Majority of the classes in libecasound fall to this category. They
779
implement the behaviour of some object interface type. As other
780
parts of the library only use the object interfaces, these
781
implementation classes are fairly isolated. Changes made inside object
782
implementation have no effect to other parts of the library.
783
Similarly new object interface implementations can be added without
784
modifying the core classes.
791
eca-logger.h - ECA_LOGGER
792
-------------------------
794
Singleton class that provides an interface to Ecasound's logging
795
subsystem. Libecasound sends all log messages to this interface.
796
The actual logger implementation can be done in many ways. For example
797
in the console mode user-interface of Ecasound, TEXTDEBUG class
798
implements the ECA_LOGGER_INTERFACE class interface. It sends all
799
messages that have a suitable debug level to the console's standard
800
output. On the other hand, in qtecasound, ECA_LOGGER_INTERFACE is
801
implemented using a Qt widget.
803
New ECA_LOGGER_INTERFACE implementations can be registered at
804
runtime with the ECA_LOGGER::attach_logger() member
805
function (declared in eca-logger.h).
810
Object maps are central repositories for commonly used objects.
811
Their main purpose is to add flexibility to handling different
812
object types - especially to handling dynamic addition and removal
813
of whole object types. They provide the following services:
815
- listing all object types in any of the available
816
categories (for instance, list all effect types)
818
- creating new object instances based on keyword strings
819
(for instance, returns an mp3 object if "foo.mp3" is given
822
- adding new object types (object map item is identified by
823
tuple of "keyword, regex expression, object type")
825
- removing object types
827
- reverse mapping objects back to keyword strings
829
In Ecasound, all access to object maps goes throuh the library-wide
830
ECA_OBJECT_FACTORY class, which provides a set of static functions
831
to access the object maps.
833
This system may sound a bit complex, but in practise it is quite
834
simple and makes a lot of things more easier. For instance, when
835
adding new object types to the library, you only have to add one
836
function call which registers the new object; no need to modify any
837
other part of the library. It also makes it possible to add new
838
types at runtime, including dynamically loaded plugins.
840
One special use-case is where an application linked against
841
libecasound adds its own custom object types on startup. All parts
842
of libecasound can use the custom objects, although they are not
843
part of library itself.
845
All objects defined in libecasound are registered in the file
846
eca-static-object-maps.cpp.
848
eca-object.h - ECA_OBJECT
849
-------------------------
851
A virtual base class that represents an Ecasound object. All objects
852
handled by the object factory must inherit this class.
854
eca-object-factory.h - ECA_OBJECT_FACTORY
855
-----------------------------------------
857
The public interface to Ecasound's object maps. All its functions
860
.. #################################################################
861
.. #################################################################
863
Adding new features and components to Ecasound?
864
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
866
Things to remember when writing new C++ classes
867
===============================================
871
Copy constructor and assignment operator
872
----------------------------------------
874
Always take a moment to check your copy constructor and the assign
875
operation (=operation()). Basicly you have three alternatives:
877
- Trust the automatically created default definitons. If you don't
878
have any pointers as data members, this isn't necessarily a bad
879
choice at all. At least the compiler remembers to copy all members!
881
- If you have pointers to objects as class data members, you should
882
write definitions for both the copy-constructor and the assign
885
- If you are lazy, just declare the two functions as null
886
functions, and put them in _private_ access scope. At least this way
887
nobody will use the functions by accident!
892
To implement a new audio object type, you must first select which
893
top-level class to derive from. Usually this is either AUDIO_IO
894
(the top-level class), AUDIO_IO_BUFFERED (a more low level interface)
895
or AUDIO_IO_DEVICE (real-time devices).
897
The second step is to implement the various virtual functions declared
898
in the parent classes. These functions can be divided into four
899
categories: 1) attributes (describes the object and its capabilities),
900
2) configuration (routines used for setting up the object), 3) main
901
functionality (open, close, input, output, etc) and 4) runtime
902
information (status info).
904
Adding the new object to Ecasound is much like adding a new effect
905
(see the next section). Basicly you just add it to the makefiles and
906
then register it to the appropriate object map (see below).
908
Checklist for Audio Object Implementations
909
------------------------------------------
911
1. Check the read_buffer() and write_buffer() change the
912
internal position with either set_position_in_samples()
913
or change_position_in_samples() functions of ECA_AUDIO_POSITION.
914
Also, when writing a new file, extend_position() should
915
also be called. All this is done automatically if using
916
read_samples() and write_samples() from AUDIO_IO_BUFFERED.
917
2. If implementing a proxy object, separately consider all public
918
functions of audioio-proxy.h (whether to reimplement or use
920
3. Check that open() and close() call AUDIO_IO::open() and
921
AUDIO_IO::close(), and in the right order.
922
4. If the object supports seeking, seek_position() must
925
Effects and other chain operators
926
=================================
928
Write a new class that inherits from CHAIN_OPERATOR or any of its
929
successors. Implement the necessary routines (init, set/get_parameter,
930
process and a default constructor) and add your source files to
931
libecasound's makefiles. Then all that's left to do is to add your
932
effect to libecasound/eca-static-object-maps.cpp,
933
register_default_objects(). Now the new effect can be used just
934
like any other Ecasound effect (parameters control, effect presets, etc).
936
Another way to add effects to Ecasound is to write them as LADSPA
937
plugins. The API is well documented and there's plenty of
938
example code available. See http://www.ladspa.org
939
for more information.
941
Differences between audio objects and chain operators
942
=====================================================
944
Design-wise, audio objects and effects (chain operators) aren't that
945
far away from each other. Many audio apps don't separate these
946
concepts at all (for instance most UG based synthesizers). In Ecasound
947
though, there are some differences:
951
- audio objects can be opened for reading writing or read\&write
952
- effects are modeless
953
- audio objects read from, or write to a buffer
954
- effects get a buffer which they operate (in-place processing)
958
- audio objects have a distinct audio format (sample rate, bits,
960
- effects should be capable of accepting audio data in any format
961
(this is usually easy as Ecasound converts all input data to its
966
- audio objects can be opened, closed, prepared, started and stopped
967
- effects don't have a running state
971
- audio objects have length and position attributes
972
- effects just process buffers and don't know about their position
974
A good example of the similarity between the two types are LADSPA
975
oscillator plugins. Although they are effects, you can easily use them
976
as audio inputs by specifying:
980
"ecasound -i null -o /dev/dsp -el:sine_fcac,440,1"
985
Ecasound supports LADSPA-effect plugins (Linux Audio Developer's Simple
986
Plugin API). See LAD mailing list web site for
987
more info about LADSPA. Other useful sites are
988
LADSPA home page and LADSPA documentation.
993
Adding a new interactive mode commands requires changes to the
997
- libecasound/eca-iamode-parser_impl.h: Unique id for the new command
998
has to be added to enum Commands.
1000
- libecasound/eca-iamode-parser.cpp: The new command must be added
1001
to the appropriate register_commands_*() function.
1003
- libecasound/eca-iamode-parser.cpp: The new command must be added
1004
to the appropriate action_requires_*() sets.
1006
- libecasound/eca-control.cpp: The actual implementation of the
1009
- Documentation/ecasound-iam_manpage.yo: Documentation must be
1012
.. #################################################################
1013
.. #################################################################
1015
Application development using the Ecasound framework
1016
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1018
Console mode ecasound - {[}all languages{]}
1019
===========================================
1021
This is the easiest way to take advantage of Ecasound features in your
1022
own programs. You can fork ecasound, pipe commands to ecasound's
1023
interactive mode or you can create chainsetup (.ecs) files and load
1024
them to ecasound. You'll be able to do practically anything. The only
1025
real problem is getting information from ecasound. You'll have to
1026
parse ecasound's ascii output if you want to do this. To make this
1027
a bit easier, Ecasound offers the wellformed output mode
1028
and dump-* commands. These can be used to easily parse configuration and
1031
Ecasound Control Interface - {[}C++, C, Python{]}
1032
=================================================
1034
Idea behind Ecasound Control Interface (ECI) is to take a subset of
1035
functionality provided by libecasound, write a simple API for it, and
1036
port it to various languages. At the moment, at least C++, C and
1037
Python implementations of the ECI API are available and part of the
1038
main Ecasound distribution. ECI is heavily based on the Ecasound
1039
Interactive Mode (EIAM), and the services it provides.
1041
Specific tasks ECI is aimed at:
1043
- 1. automating (scripting in its traditional sense)
1044
- 2. frontends (generic / specialized)
1045
- 3. sound services to other apps
1047
NetECI - {[}various{]}
1048
======================
1050
NetECI is a network version of the ECI API. When Ecasound is
1051
started in daemon mode (the --daemon option), it creates
1052
a server for incoming TCP connections. Client applications
1053
can connect to this socket and use the connection to
1054
control and observe the active session. Multiple clients
1055
can connect to the same session.
1057
The protocol is identical to one used in ECI. Clients
1058
write EIAM commands to the socket, followed by a CRLF pair.
1059
The server will reply using the well-formed output mode
1062
See implementation of ecamonitor (part of ecatools),
1063
for a working example.
1065
Libecasound's ECA_CONTROL class - {[}C++{]}
1066
===========================================
1068
Note! Direct use of libecasound and libkvutils is
1069
not recommended anymore! Please use the Ecasound Control Interface
1072
By linking your program to libecasound, you can use the ECA_CONTROL
1073
class for controlling Ecasound. This is a large interface class that
1074
offers routines for controlling all Ecasound features. It's easy
1075
to use while still powerful. Best examples are the utils in ecatools
1076
directory (most of them are just a couple screenfuls of code). Also,
1077
qtecasound and ecawave heavily use ECA_CONTROL. Here's a few lines of
1083
| ECA_SESSION esession;
1084
| ECA_CONTROL ctrl (&esession);
1085
| ctrl.new_chainsetup("default");
1086
| [... other setup routines ]
1087
| ctrl.start(); // starts processing in another thread (doesn't block)
1090
If you don't want to use threads, you can run the setup in
1096
| ECA_SESSION esession;
1097
| ECA_CONTROL ctrl (&esession);
1098
| ctrl.add_chainsetup("default");
1099
| [... other setup routines ]
1100
| ctrl.run(); // blocks until processing is finished
1103
Ecasound classes as building blocks - {[}C++{]}
1104
===============================================
1106
Note! Direct use of libecasound and libkvutils is
1107
not recommended anymore! Please use the Ecasound Control Interface
1110
You can also use individual Ecasound classes directly.
1111
This means more control, but it also means more work. Here's
1112
another short sample:
1115
| - create a SAMPLE_BUFFER object for storing the samples
1116
| - read samples with an audio I/O object - for example WAVEFILE
1117
| - process sample data with some effect class - for example EFFECT_LOWPASS
1118
| - maybe change the filter frequency with EFFECT_LOWPASS::set_parameter(1, new_value)
1119
| - write samples with an audio I/O object - OSSDEVICE, WAVEFILE, etc.
1122
.. #################################################################
1123
.. #################################################################
1125
Protocols and Interfaces
1126
~~~~~~~~~~~~~~~~~~~~~~~~
1128
Ecasound Interactive Mode - Well-Formed Output Mode
1129
===================================================
1131
By issuing the EIAM command "int-output-mode-wellformed",
1132
Ecasound will start printing all messages using the following
1137
| <message> = <loglevel><sp><msgsize>(<genmsg> | <returnmsg>)
1139
| <loglevel> = <integer> ; loglevel number
1140
| <msgsize = <integer> ; size of content in octets
1141
| <genmsg> = <contentblock> ; generic log message
1142
| <returnmsg> = <sp><returntype><contentblock>
1143
| ; EIAM return value message
1144
| <contentblock> = <crlf><content><crlf><crlf>
1145
| ; actual content of the message
1146
| <returntype> = "i" | "li" | "f" | "s" | "S" | "e"
1147
| ; type of the return value (see ECI/EIAM docs)
1148
| <content> = *<octet> ; zero or more octets of message content
1150
| <sp> = 0x20 ; space
1151
| <octet> = 0x00-0xff ; 8bits of data
1152
| <crlf> = <cr><lf> ; new line
1153
| <cr> = 0x0d ; carriage return
1154
| <lf> = 0x0a ; line feed
1155
| <integer> = +<digit> ; one or more digits
1156
| <digit> = 0x30-0x39 ; digits 0-9
added
removed
Documentation/programmers_guide/ecasound_programmers_guide.txt
