/******************************************************************************\
 * Copyright (c) 2004-2008
 *
 * Author(s):
 *	Volker Fischer
 *
 ******************************************************************************
 *
 * This program is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free Software
 * Foundation; either version 2 of the License, or (at your option) any later
 * version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program; if not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
\******************************************************************************/

llcon
-----

Low-Latency Connection / client and server (http://llcon.sourceforge.net)


INTRODUCTION:
The llcon software enables musicians to play together over the internet. The
way it works is that there must be one server which collects the audio data
from each client, mixes all together and sends the mix back to each client.
The minimum internet connection speed at each client must be 256 kbps upstream
and 1 Mbit downstream. The server software must be located at a server with a
very fast internet connection (at least 1 Mbps for up- and downstream) and a
very low ping time. To get satisfactory results, the ping time from the client
computer to the server should not exceed 30 ms average and the network jitter
should be as low as 2-5 ms (To get a low ping time on DSL connections, an
extra option "DSL fast path" should be enabled by your internet provider).

Technical details
To get sufficient results, a sample rate of 24 kHz (mono channel) was chosen.
The audio compression algorithm IMA-ADPCM with very low delay is used which
results in a raw compressed audio data rate of 96 kbps. First tests showed
that an upstream of 128 kbps is too slow for using the llcon software. At
least 256 kbps upstream bandwidth is required.

The llcon software package includes both, the server and the client
functionality which can be selected by using command line arguments.


MANUAL:
For starting server type ./llcon -s

Start the llcon server on a remote computer with fast internet access. Start the
llcon client on your local computer and connect your sound card with your
instrument/microphone and headphone and type in the IP address of the server.
There are levelers for adjusting the sound card (in/out) and network buffer sizes.
It seems that 2 blocks for network buffer is an optimal choice. For the sound card
buffer, try to make them as short as possible by watching the LEDs below the
levelers (they should stay green).

For test purpose it is possible to run server and client on the same computer. For
this setup first start the server and then the client. Type in 127.0.0.1 for the
IP address in the client software.


EXTERNAL CODE:
This code contains open source code from different sources. The developer(s) want
to thank the developer of this code for making their efforts available under open
source:

- audio reverberation code: by Perry R. Cook and Gary P. Scavone, 1995 - 2004
	(taken from "The Synthesis ToolKit in C++ (STK)")

- IMA-ADPCM: by Erik de Castro Lopo

- some parts are taken from the project "Dream: a PC-based Digital Radio Mondiale
	(DRM) receiver" written by one of the llcon authors, Volker Fischer