3rdparty/iaxclient/README

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