=======================================================================
*** Ecasound - README                    (maintainer: Kai Vehmanen) ***
=======================================================================
-----------------------------------------------------------------------
 What is it?
-----------------------------------------------------------------------

Ecasound is a software package designed for multitrack audio
processing. It can be used for simple tasks like audio playback, 
recording and format conversions, as well as for multitrack effect 
processing, mixing, recording and signal recycling. Ecasound supports 
a wide range of audio inputs, outputs and effect algorithms. 
Effects and audio objects can be combined in various ways, and their
parameters can be controlled by operator objects like oscillators 
and MIDI-CCs. A versatile console mode user-interface is included 
in the package.

Primary platform for running Ecasound is Linux. Ecasound also
works on many UNIX-derived systems such as FreeBSD and Solaris. 
Limited support for Windows is available through Cygwin.

-----------------------------------------------------------------------
 How do you?
-----------------------------------------------------------------------

... spell the name? 

I haven't been very consistent with this, but at least in principle, 
when capitalized, the name refers to the whole package. When in lower 
case, it refers to the console mode application which happens to have 
the same name.

"Ecasound" = the whole package
"ecasound" = the console mode client application (binary)

... pronounce the name?

Any way you want! :) Personally I say something to the effect of
"eck-uh-sound". Start from "megasound", and omit pronouncing the 
'm' at the start, and replace 'g' with a sharper 'uh' sound.

-----------------------------------------------------------------------
 Why?
-----------------------------------------------------------------------

I started developing Ecasound because I needed an application to
record, process and mix my own music. The first versions of Ecasound 
ran under IBM OS/2. I used those versions for finalizing my analog 
4-track recordings. 

The analog 4-track - Tascam 414 - was a nice tool, but it 
had its limits. So eventually I started looking for PC software 
that supported multitrack recording. The first programs I used were 
for Windows. I still used the OS/2 version of Ecasound for effects 
processing and finalizing my mixes. Although I'm not fanatical
about operating systems, I did prefer (and still do) to use Linux
for my computing needs. I also hate rebooting between multiple 
systems all the time, so it was time to do a port.

When I ported Ecasound to Linux, a lot of functionality was rewritten 
from scratch. During this work I also added multitrack capabilities
to Ecasound. It took quite a lot of effort to put it all back 
together, but in the end I reached the point where I could do 
all the audio processing tasks on Linux. As an additional benefit
I now had source code for - and thus control over - all tools I used
for audio processing.

Nowadays I still use Ecasound for my music projects. This is also
the primary motivation for continuing the development work. There is 
always something to improve.

-----------------------------------------------------------------------
 Requirements
-----------------------------------------------------------------------

To run Ecasound, you need...:

- operating system that provides standard POSIX interfaces; has been 
  tested with various combinations of GNU/Linux (Linux 2.2/2.4/2.6 and 
  glibc 2.1/2.2/2.3 combinations), FreeBSD 4.x, Solaris 2.8 and 
  Cygwin 1.3.20
- POSIX threads support; has been tested with glibc linuxthreads 
  and the Native POSIX Thread Library (NPTL)
  
Optional when running Ecasound:

- for soundcard input/output: OSS, OSS/Lite or ALSA drivers
- for JACK-support, the JACK runtime environment
- for mp3 support, mpg123 (input) and lame (output) packages
- for tracker module support, MikMod package
- for .aiff/.au/.snd support, libaudiofile (SGI audio file) library
- for Ogg Vorbis support, the vorbis-tools package (ogg123 and vorbize)
- for .mid input support, Timidity++
- for aRts support, the aRts server package
- for higher quality resampling, libsamplerate

To compile Ecasound, you also need...:

- standard C++ build environment; tested with egcs 1.1.2, 
  gcc 2.91.66, gcc 2.95.3, gcc 3.0.x, gcc 3.1.x, gcc 3.2.x, 
  gcc-3.3 and Sun Workshop 6 C5.2 C++ (STL and exceptions 
  need to be supported)
- GNU make, automake and autoconf packages

Optional when compiling Ecasound:

- for pyecasound, the Python devel package
- for curses support, the ncurses devel package
- for LADSPA support, the LADSPA SDK package
- for ALSA support, the ALSA devel package
- for JACK support, the JACK devel package
- for .aiff/.au/.snd support libaudiofile devel package
- for aRts support, the aRts C-API devel package
- for higher quality resampling, libsamplerate devel package

-----------------------------------------------------------------------
 Installing
-----------------------------------------------------------------------

First of all, you should first try to install from a binary package 
(in rpm, dpkg, etc format, depending on your system). This is probably 
the easiest and most straigthforward way to install Ecasound.

If you need to compile Ecasound, the file 'INSTALL' contains detailed 
instructions. To build RPM source and binary packages from the 
source tar package, issue "rpm -ta ecasound-x.y.x.tar.gz".

-----------------------------------------------------------------------
 Documentation
-----------------------------------------------------------------------

Ecasound documentation is updated whenever new features are added 
or old features have been modified. Some things are not documented
in great detail, but on the other hand, all documentation is kept
up-to-date. The primary documentation sources are:

- Ecasound User's Guide
- Ecasound Programmer's Guide
- Ecasound Control Interface Guide
- manual pages
	- ecasound(1)
	- ecatools(1)
	- ecasound-iam(1)
	- ecasoundrc(5)
- misc HTML-formatted docs (Documentation/ directory)
- command line help
	- ecasound --help

Probably the best place to start is the examples section of 
Ecasound's HTML-documentation (Documentation/examples.html).

-----------------------------------------------------------------------
 Mailing lists
-----------------------------------------------------------------------

ecasound-announce@wakkanet.fi:
	A read-only list for announcements concerning Ecasound and 
	Ecawave.

ecasound-list@wakkanet.fi:
	A general discussion forum for Ecasound/Ecawave
	developers and users. Announcements of new versions, bug 
	warnings, etc will be posted to this list. If you have
	problems compiling, installing or using Ecasound/Ecawave, this 
	is a good place to ask for help. Reports of working 
	software/hardware combinations are also welcome. You can
	browse 	the message archives at
	http://www.wakkanet.fi/~kaiv/ecasound/ecasound-list/current/ 

ecasound-cvs@wakkanet.fi:
	A read-only list for reports about Ecasound CVS activity.

You can join the lists by sending subscribe message to
majordomo@wakkanet.fi. You can also join using the following 
web front-end: http://eca.cx/mlists.html

-----------------------------------------------------------------------
 Web sites
-----------------------------------------------------------------------

Ecasound home site
- http://www.eca.cx/ecasound

Distribution packages
- http://ecasound.seul.org/download/

Eca projects page (links, apps based on Ecasound, etc)
- http://www.eca.cx

Examples of real-life Ecasound usage
- http://www.eca.cx/ecasound_users.html

-----------------------------------------------------------------------
 About free open-source software (FOSS) development
-----------------------------------------------------------------------

You should keep in mind that FOSS [1] development process differs
greatly from closed commercial development. Active participation, 
both from developers and users, is what pushes a FOSS project forward. 
Every succesful FOSS project has an active userbase behind it. This 
means that your comments, ideas and bug reports are extremely
important. If something does not work, or some feature is missing, 
be active. Either try to fix the problem yourself, or report it
on the ecasound-list mailing list.

[1] Although Ecasound is free software (http://www.gnu.org), it also 
    fits the definition of open-source software (http://www.opensource.org/).
    Although the two initiatives have different goals, they also share
    a lot in common. I use the term FOSS to refer to both of them,
    while still acknowledging the difference between the two.

-----------------------------------------------------------------------
 Stable and development versions
-----------------------------------------------------------------------

Although publically released versions are called stable, this is not 
a guarantee of any kind. Before releases I run through a small set 
of test cases to verify that all basic features are working. I also 
use the latest versions for my own work. But other than that, there
is no guarantee that Ecasound won't eat your data. On the other hand,
as Ecasound is free software, you have the possibility to review
Ecasound's source code, perform tests, and fix any bugs you might find. 
The more people there are that do this, the more stable Ecasound 
will eventually become! So join the fun! :)

-----------------------------------------------------------------------
 Authors
-----------------------------------------------------------------------

See the file 'AUTHORS'.

-----------------------------------------------------------------------
 Thanks to
-----------------------------------------------------------------------

DotCX (www.nic.cx) - For providing the 'eca.cx' domain.
Endersz, Viktor - For sending me the adv.compressor source code!
LAD members - Always a great source of inspiration! Special thanks
	      to Paul Davis, who has kept on pushing Linux audio 
	      forward all these years.
Philips, Dave - The 'Linux Sound & MIDI' website was the reason
		why I initially got interested in Linux audio!
SEUL (www.seul.org) - For hosting Ecasound ftp, http and CVS sites.
Wakkanet Oy (www.wakkanet.fi) - For hosting the Ecasound web site.

-----------------------------------------------------------------------
 Licensing/distribution policy
-----------------------------------------------------------------------

Copyright (C) 1997-2003 Kai Vehmanen

Ecasound is freely distributable according to the terms of the 
GNU General Public License (see the file 'COPYING.GPL').

This program is distributed without any warranty. See the file 
'COPYING.GPL' for details. 

As an exception to the above, the C, C++ and python implementations 
of the Ecasound Control Interface (ECI) are licensed under the LGPL 
(see the file 'COPYING.LGPL'). This allows writing ECI applications 
that are not licensed under GPL.

=======================================================================
