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.