PAUD - Parted And Utilities Disk Files

Copyright 2004, 2005 Andrew Popov (apopov@etel.ru)

This file is part of Phone - an IP telephony application.
This is a text file describing Phone installation and use.

Phone 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.

Phone 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 Phone; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

CONTENTS
1.OBTAINING PHONE
2.SYSTEM REQUIREMENTS
3.INSTALLING PHONE
4.COMPRESSION AND ENCRYPTION CODECS
5.RUNNING PHONE
6.BUILDING PHONE FROM SOURCE CODE
7.PHONE INTERNALS
8.EXTENDING PHONE
9.KNOWN PROBLEMS AND CONTACT INFORMATION

1.OBTAINING PHONE
Phone is available for download from SourceForge.net in source code 
and binary form. Binary files have been compiled using RedHat Linux 9 
and MS Windows 2000. 

2.SYSTEM REQUIREMENTS
To use Phone, you will need:
-UNIX/Linux or MS Windows operating system.
-If you use UNIX/Linux, your distribution must support /dev/audio.
-An installed sound card and headphones/microphone.
-IP networking hardware and software. For Windows, winsock2 
should be present.
Processor and memory requirements depend on the codec being used with 
Phone; they are negligible if no codec is selected resulting in 
uncompressed, unencrypted sound stream.

3.INSTALLING PHONE
x86 Linux and Windows users have an option of installing pre-built 
binary files. On other platforms, you can build Phone from source 
code distribution. Please refer to section 6 below for details.
If you choose to use binary distribution, simply copy phone 
(or phone.exe in case of Windows) to the directory of your choice.
Additionally, if you prefer to use compression and/or encryption, 
you will need to copy the corresponding codec libraries supporting 
Phone codec interface. Please refer to section 4 of this document 
for further discussion of codecs.
Before running Phone, please make sure that your hardware and system 
software are configured properly for audio playback and recording and 
adjust sound volume controls.
On Linux, you can execute the following commands to test sound recording
and playback:
cat /dev/audio > record
cat record > /dev/audio
On Windows, you can use Sound Recorder accessory application.
Also, make sure your IP network environment allows you to connect 
to the second party's computer (e.g., using ping utility).

4.COMPRESSION AND ENCRYPTION CODECS
Phone can use compression and/or encryption codec libraries specified 
on its command line (see section 5 below). In order to be used with 
Phone, a codec library must implement Phone codec interface. Please 
refer to section 8 for details.
At the time of this writing, only ITU G.726 ADPCM compression codec is 
included in the distribution of Phone. The codec is based on the code 
from ITU-T STL 2000, published as ITU-T Recommendation G.191 under 
"ITU-T General Public License" which is distributed in the file 
gen-lic.txt.
G.726 ADPCM Codec library name is libadpcm.so for UNIX/Linux and 
adpcm.dll for Windows. The codec supports 40, 32, 24 and 16 kbit/sec 
stream (encoding/decoding mode numbers 0, 1, 2 and 3, respectively).
This codec provides adequate sound quality while allowing communication 
over slow network connections. Although there is still room for 
optimization, processor and memory requirements of this codec are 
quite modest, even for rather old computers.

5.RUNNING PHONE
The phone command is used to establish voice communication with another 
host. The general command line notation is as follows:
phone [-c <codec file> [-n <number>]] <server port> [<server IP address>]
If Phone is invoked without <server IP address> argument, it operates in 
server mode and prepares to accept a client connection on the <server 
port> specified. Otherwise, Phone enters client mode by trying to connect 
to the <server IP address> and <server port> provided.
The options are as follows:
-c <codec file>	specifies the file name and, optionally, relative or 
absolute path of the compression or encryption codec.
-n <number>			specifies the encoding/decoding mode number. If -c option 
is present, but -n is not, then the default mode number of 0 is implied.
It is an error to specify -n without -c.
To close the program gracefully, hit 'q' key.
Examples:
Since Phone currently allows only one-to-one communication, first one 
party should start Phone in server mode waiting, for example, on port 
12345, as follows:
phone 12345
Then the other party can connect as a client:
phone 12345 127.0.0.1
Needless to say, port number has to be the same for server and client and 
'127.0.0.1' must be replaced with a valid IP address of the server party.
Upon successful connection, Phone will print the corresponding message, 
which for the server party includes the presumed IP address of the client.
After that the parties should be able to talk (almost) like over the 
telephone.
Optionally, codec name and encoding/decoding mode number can be specified 
on the command line to conserve network bandwidth. Let's assume that codec 
files are located in 'lib' subdirectory of the current directory. Then the 
following command will start Phone on a UNIX/Linux machine in server mode 
waiting on port 12345 using mode 2 of G.726 ADPCM compression codec:
phone -c lib/libadpcm.so -n 2 12345
The same can be accomplished on a Windows computer with the following 
command:
phone -c lib\adpcm.dll -n 2 12345
Then the other party running UNIX/Linux can connect as a client as 
follows:
phone -c lib/libadpcm.so -n 2 12345 127.0.0.1
Or, in the case of Windows:
phone -c lib\adpcm.dll -n 2 12345 127.0.0.1
Obviously, both parties should use the same codec and mode number if they 
expect to hear intelligible speech.

6.BUILDING PHONE FROM SOURCE CODE
Binaries can be built from source distribution on UNIX systems using 
supplied makefile, or on Windows systems using MS Visual Studio 6 
workspace/project files.
By default, a full-duplex version of Phone is built which enables 
bi-directional communication between client and server. Under certain 
circumstances, however, it may be desirable to only allow unidirectional 
transmission of voice data. For example, one may wish to run both client 
and server on the same host for testing purposes, but the DSP device 
available might not be writable by more than one process at a time.
Alternatively, network configuration or security requirements may prohibit 
two-way communication. Further, some applications only require 
uni-directional transmission of voice data and the computational and 
bandwidth overhead of encrypting/decrypting and transmitting an unused 
stream of data is unacceptable. One of the following macros can be defined 
when building Phone to enable half-duplex operation: SERVER_DSP_READ_ONLY 
or CLIENT_DSP_READ_ONLY. If Phone is built with SERVER_DSP_READ_ONLY macro 
defined, the server instance opens DSP device in read-only mode while the 
client instance opens DSP device in write-only mode. Thus, voice data is 
only transmitted from server to client. Defining CLIENT_DSP_READ_ONLY macro, 
on the opposite, results in voice data flowing from client to server.
There is an extra option available for testing/troubleshooting Phone on 
UNIX/Linux machines. Instead of the above mentioned macros, you can define 
either UNIX_SERVER_USE_RECORD or UNIX_CLIENT_USE_RECORD.
When Phone is built with UNIX_SERVER_USE_RECORD macro defined, the server 
instance attempts to read mu-law-encoded voice samples from a file called 
"record" (without quotes) in the current directory. The client instance 
opens DSP device for reading and writing, just like it does by default.
With UNIX_CLIENT_USE_RECORD, the client instance reads "record" file while 
the server operates on DSP device in read-write mode.
Next follow a few example commands that can be used to build various 
flavours of Phone:
make
builds standard full-duplex release flavour suitable for 2-way 
communication. This is appropriate for most users.
make DEFINE=SERVER_DSP_READ_ONLY
builds half-duplex release flavour to transmit voice data from server to 
client instance.
cat /dev/audio > record
records mu-law-encoded samples to the file called "record". 
make DEFINE=UNIX_CLIENT_USE_RECORD FLAVOUR=debug
builds debug flavour where the client instance reads "record" file of voice 
samples and the server instance reads from and writes to the DSP device. 
This flavour is only available when building on UNIX/Linux systems.
To build various flavours of Phone without make utility (e.g. on MS Windows 
systems), please refer to your development environment documentation for 
information about defining macros and building debug/release flavors.

7.PHONE INTERNALS
Phone software consists of 3 subsystems:
-Main program including initialization, command-line argument parsing, 
networking and data transmission code. This is contained in files 
phone.h and phone.c.
-Buffer queue routines implementing a ring buffer queue. Phone uses 
two queues: one for incoming sound data from the network, another for 
outbound data from the soundcard's DSP device. In an ideal world, recorded 
sound data could travel in an even stream without interruption and always 
arrive to its destination right in time for playback. In practice, data 
may come too soon (before the previous chunk has been played back) or too 
late. Buffer queue allows to avoid losing early-arriving sound samples and 
gaps in sound playback. Buffer queue is circular so that it never overflows:
if data exceeds queue capacity, the queue simply overwrites its tail.
Buffer queue is implemented in files queue.h and queue.c.
-Windows Waveform Audio buffering routines. MS Windows' Waveform Audio 
interface requires the use of at least double-buffering scheme: at any 
time, while one buffer is being played back (or recorded), another can 
be processed by the program. This is done by the OSS sound driver 
automatically on Linux, hence the relevant functionality is only compiled 
in Windows version of Phone. Waveform Audio buffering code can be found in 
files soundbuf.h and soundbuf.c.
To enable interested third-party developers to implement compression or 
encryption codecs, Phone defines a simple codec interface in codec.h. 
Further details are provided in section 8 below.
Next follows the data flow diagram illustrating Phone application 
architecture:
                                DSP
                               /   ^
                              v     \
                        rawbufin   rawbufout
                             |       ^
                             v       |
                        encoder     decoder
                              \     ^
                               v   /
                             encbufio
                               /   ^
                              v     \
                        queueout   queuein
                             |       ^
                             v       |
                       encbufout   encbufin
                              \     ^
                               v   /
                                NET
ITU G.726 ADPCM compression codec is also included in Phone distribution.
It consists of the following modules:
-ITU-T implementation of G.725 ADPCM encoding and decoding algorithms 
supplied without modification in files g726.h and g726.c.
-Phone codec interface wrapper contained in adpcm.h and adpcm.c.
Additionally, test program for UNIX/Linux is provided. This auxiliary 
program implements test sequences to exercise buffer queue and codec 
functionality. Test program is implemented in files test.h and test.c.

8.EXTENDING PHONE
Interested developers are welcome to extend Phone functionality by 
implementing new compression and/or encryption codecs. Alternatively, 
an existing codec can be wrapped in Phone codec interface for 
compatibility. ITU G.726 ADPCM compression codec included in Phone 
distribution is an example of this approach.
Phone codec interface is declared and documented in codec.h header file.
The idea is that each codec library can operate in a number of encoding/
decoding modes. GetCaps capability enumerating function describes those 
modes in terms of encoder and decoder function pointers, as well as 
minimal raw and encoded buffer sizes. Phone is guaranteed to supply 
buffers whose size is a multiple of those minimal values. This should 
satisfy the requirements of any consant-rate encoding algorithm, sample- 
or frame-oriented. Basically, GetCaps capability enumerating function, 
encoder and decoder functions are all that a codec library needs to 
expose in order to work with Phone. 
One important thing to note is that Phone will pass mu-law encoded 8-bit 
samples to the encoder and expect the same format from decoder function.
However, no commitment can be made at this time regarding the support of 
this interface in future versions of Phone.

9.KNOWN PROBLEMS AND CONTACT INFORMATION
-The current implementation of Phone can only be built on those UNIX 
systems that offer dlopen dynamic library loading interface. However, 
Windows DLL API is supported.
-The current version works with mu-law encoded samples, while all 
previous ones used linear PCM samples. Thus, the latest version is not 
compatible with older ones.
-g726.c file may generate a lot of compiler warnings. The code in g726.h 
and g726.c has been taken in its entirety and without modification from 
ITU-T STL 2000. The codec appears to run correctly, though.
-Phone codec interface described in section 8 is not frozen yet and 
expected to evolve as more requirements are gathered while experimenting 
with different kinds of compression and encryption codecs.
-No security is in place unless an encryption codec is specified. Be 
careful, if Phone is launched in server mode, anyone can connect and 
eavesdrop! And anyone can intercept (and alter) the traffic in transit.
Constructive criticism, bug reports and suggestions are welcome at 
apopov@etel.ru.