1=======================================================================
2INTRODUCTION
3
4This is iaxclient, a portable IAX/IAX2 protocol telephony client library.
5
6The library itself is in the directory "lib", located in the same
7directory as this README file.
8
9The library is designed to build for multiple platforms, and currently
10supports Linux, MacOSX, Solaris, and Win32 platforms. It is designed to handle
11the "backend" of IAX telephony operations, including call handling,
12network protocols, audio encoding/decoding, and audio capture/playback.
13In it's future, it may be extended to also handle video encode, decode,
14capture and playback.
15
16There are also sample clients, which use the library, included here.
17
18Currently, these are all stored under the "simpleclient" directory, and
19there are three of them:
20
21simpleclient/testcall: A simple command-line oriented test program,
22 useful for testing and debugging. It supports
23 all of the same platforms as the library itself.
24
25simpleclient/wx: A wxWindows (see wxwindows.org) based GUI
26 client. This client also supports all of the
27 same platforms as the library itself.
28
29simpleclient/WinIAX: A MSVC/Win32 client. This only works with
30 Win32, obviously, and was contributed by
31 Faizan "Tili" Naqvi <faizan@tilizone.com>
32
33simpleclient/tkiaxphone A command-line client, with a Tcl/Tk GUI
34 client that drives it. It should work on
35 all the platforms
36
37
38The home page for iaxclient is "http://iaxclient.sourceforge.net/"
39
40Up-to-date versions of iaxclient are available from a sourceforge SVN
41repository.
42
43CVS tarballs are also available as a link from the home page.
44
45
46=======================================================================
47LICENSES
48
49
50The iaxclient library itself, is provided under the terms of the LGPL:
51
52 This library is free software; you can redistribute it and/or
53 modify it under the terms of the GNU Library General Public
54 License as published by the Free Software Foundation; either
55 version 2 of the License, or (at your option) any later version.
56
57 This library is distributed in the hope that it will be useful,
58 but WITHOUT ANY WARRANTY; without even the implied warranty of
59 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
60 Library General Public License for more details.
61
62 You should have received a copy of the GNU Library General Public
63 License along with this library; if not, write to the Free
64 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
65 MA 02111-1307, USA
66
67The iaxclient library may also include, when compiled, works distributed
68under other licenses. See those directories and source files for
69specifics. These include:
70
71 libiax: (c) 2001 Mark Spencer under the LGPL.
72 libiax2: (c) 2001 Mark Spencer under the LGPL.
73 gsm encoder: Copyright 1992, 1993, 1994 by Jutta Degener
74 and Carsten Bormann, Technische Universitaet Berlin
75 (free license, terms in gsm/copyright)
76 portaudio: Copyright (c) 1999-2000 Ross Bencina and Phil Burk
77 Modified BSD style license, in portaudio/LICENSE.txt
78
79 sox tools: compand.c: Copyright 1999 Chris Bagwell And
80 Nick Bailey
81 resample.c: (not currently used) Copyright 1991
82 Lance Norskog And Sundry Contributors,
83 free licenses in source files.
84 libspeex: (c) various authors
85 BSD-like license.
86
87
88=======================================================================
89CONTRIBUTORS:
90
91IAXCLIENT itself was contributed to by:
92
93Steve Kann <stevek@stevek.com>
94Shawn Lawrence <shawn.lawrence@terracecomm.com>
95Faizan "Tili" Naqvi <faizan@tilizone.com> [Win32 VC++ build/client]
96Scott Lambert <lambert@lambertfam.org> [FreeBSD build changes]
97Michael Van Donselaar <mvand@vandonselaar.org> [Win32/MinGW build directions, UI changes, IAXComm phone ]
98Steven Sokol <ssokol@sokol-associates.com> [ Debugging, Blind Transfer ]
99Stephan Kauss <Stephan@kauss.org> [ 32-bit alignment for IAX2 ]
100Stephen Uhler <suhler@sun.com> [Solaris build, tkiaxphone]
101Steve Underwood <steveu@coppice.org> [PLC implementation from spandsp]
102Jean-Denis Girard <jd.girard@sysnux.pf> [URL Receive implementation]
103Panfilov Dmitry <dima@bdpu.org> [Basic ALSA-native audio driver]
104Mihai Balea <mihai at hates dot ms>
105Bill Welch <welch1820 at gmail dot com> [Project files for several MS development environments]
106
107
108In addition to including libiax, IAXCLIENT is also based in part on code
109included in test clients within libiax itself.
110
111The included sub-libraries, including libiax, libiax2, gsm, portaudio,
112and the sox-derived filters, were developed by others, as noted in above
113and in their sources. We couldn't have built IAXCLIENT (or, it would
114have been much more difficult!) without the great work from these
115projects.
116
117=======================================================================
118BUILDING THE LIBRARY:
119
120From the "lib" directory:
121 Linux: type "make" using standard gnu make/gcc
122 FreeBSD: type "gmake" using standard gnu make/gcc
123 MacOSX: type "make" using Apple Dev Tools (gnu make/gcc)
124 Win32: type "make" using Cygwin or Cygwin and MinGW (see below)
125 Solaris: type "gmake" using standard gnu make/gcc
126
127For a shared library, make clean, then make shared.
128You should receive a shared library (.dll, .so, .dylib, depending on your platform).
129
130Win32 Cygwin/MinGW; General:
131The Win32 build has been tested using the Cygwin Environment, and the
132MinGW port of the GCC compiler suite. Previously, we only supported
133compilation with the cygwin _and_ mingw environments installed. We are
134moving (4/20/2005) to support having the cygwin environment alone, with
135cygwin's own mingw packages, instead. Compilation of the basic sample
136clients (but not iaxcomm), works fine with cygwin alone.
137
138Cygwin Alone:
139To install cygwin, download and run http://www.cygwin.com/setup.exe
140You will need to install, in addition to the defaults, these packages:
141gcc-mingw, gcc-mingw-core, (and for C++ clients, gcc-mingw-g++).
142[please let the maintainers know if other non-default packages are
143required].
144
145There's lots of goodies available from cygwin.
146
147Once you have this installed, open the cygwin shell, and build. The
148library makefiles use the -mno-cygwin option, to create native Win32
149binaries which do _not_ require cygwin.dll, or any special runtimes.
150
151Cygwin and MinGW:
152Previously, we advocated installing cygwin environment (for Gnu Make and
153such), alongside the MinGW distribution itself, as outlined here. This
154may still be necessary for the Wx-Windows based clients like iaxcomm.
155
156http://www.mingw.org/mingwfaq.shtml#faq-usingwithcygwin for the
157MinGW FAQ entry on using MinGW with Cygwin. You do need to make sure
158that you install the Gnu "make" utility when you install cygwin.
159
160It should probably also work if you use the MSYS environment and the
161MinGW compiler, but this configuration is not as well tested.
162
163=======================================================================
164LIBRARY ORGANIZATION/DESIGN/CODING CONVENTION NOTES
165
166The iaxclient library is designed to be a small, simple library that
167encapsulates all that you need in order to make IAX protocol telephony
168programs.
169
170All exported symbols should be prefixed with "iaxc_", to avoid namespace
171collisions/pollution in programs using this library.
172
173The header file "iaxclient.h" should contain those declarations needed
174by client programs, but not rely on other headers (i.e. those from
175included libraries). The "iaxclient-lib.h" header file is the main
176header file for the library's internal declarations.
177
178
179=======================================================================
180
181SAMPLE CLIENTS
182
183The "testcall" sample program, provided in the simpleclient/testcall
184directory (above this "lib" directory) is a simple client program which
185should also be portable.
186
187The Makefile for "testcall" will automatically build or update the
188library when it it built, and the requirements for building testcall are
189the same as for the library itself.
190
191
192See README files in the other sample clients for directions for building
193these.
194
195=========================================================================
196
197CODECS
198
199The codec API is pretty straightforward; just use any of the existing
200available codecs as a guide. The only place in the main code they
201interface is the switch in audio_encode.c:create_codec
202
203ILBC
204
205Lots of people are enamored with iLBC lately, so I put this together for
206them. Personally, I prefer speex, because it seems to sound just as
207good, but has no license restrictions. With proper compilation options
208(i.e. use it's SSE optimizations), it can be made even faster than the
209iLBC reference.
210
211There is glue to build iaxclient with iLBC available in the source, but
212the source to iLBC itself is _not_ included. This is primarily because
213of the licensing issues.
214
215I'm not a lawyer, but it appears that iLBC's license would make it
216impossible to build iaxclient and link it with a GPL front-end, meaning
217a library built this way is no longer something that could be considered
218LGPL. However, you could probably build a client using iLBC and
219distribute it legally, if you follow the rules in the LGPL. So, this is
220an issue for you and your legal counsel to figure out.
221
222To actually build iaxclient with iLBC, though is very easy. Just make a
223directory under lib named iLBC, and drop the iLBC reference sources into
224it, then change CODEC_ILBC=0 to CODEC_ILBC=1 in the Makefile, and away
225you go.
226
227The source presently is set up for the draft-5 version.
228
229The iLBC license and software can be found here
230http://www.ilbcfreeware.org/software.html
231(sources are also in asterisk).
232
233=========================================================================
234
235AUDIO DRIVERS
236
237The supported audio driver for iaxclient is audio_portaudio; which uses
238a snapshot of the portaudio v19 library (included, with some minor
239modifications) to access native audio services on each platform.
240It includes support for Windows (WMME), Linux (OSS, ALSA, JACK) and
241MacOS X (CoreAudio).
242
243There is a (presently broken) WMME-native audio driver which was used
244during early development, and is no longer maintained. You probably
245don't want to use this.
246
247All three Linux PortAudio drivers are enabled by default and supporting
248libraries need to be present on the system in order to build. If you
249prefer to disable one or more of the drivers, use the USE_PA_* options
250in the main Makefile.
251
252Dmitry Panfilov has contributed a basic native ALSA driver for Linux.
253Not all features are supported with this driver. It is not compiled in
254by default, because this would add alsa libraries to the build and link
255dependencies -- and we don't have a good way of communicating that to
256applications (like pkg-config stuff, etc). To use it, though, you just
257need to change AUDIO_ALSA=0 to AUDIO_ALSA=1 in the Makefile.
258
259
260