This is a "plugin" for the Video Disk Recorder (VDR).

Written by:                  Luca Olivetti <luca@olivetti.cjb.net>

Project's homepage:          http://club.telepolis.com/l.o/vdr/

See the file COPYING for license information.


DESCRIPTION
===============================================================================
This plugin is a very simple (read: not very featureful and hopefully with
an high WAF ;-) softphone using the iax protocol (asterisk server). 
It uses the iaxclient library (http://iaxclient.sourceforge.net) to handle
every details of the call, so the plugin is just an user interface.
It needs a free (i.e that isn't used by something else, like a softdevice
plugin), full-duplex sound card.


BUILD
===============================================================================
A CVS checkout of the library is included in the iaxclient subdirectory, 
so the usual way to build a plugin should be enough.
Due to licensing issues the library doesn't include iLBC support but it's
possible to include it. See the iaxclient/README file to know how to do it.
Remember to rebuild the plugin afterwards, othewise you won't be able to
select the iLBC codec.


SETUP PARAMETERS
===============================================================================
-iax server
 The name or address of the default iax server you're going to use.

-username
 your username at said server.

-password
 your password at said server.

-register
 if you want to receive incoming calls you need to register to the server,
 otherwise you'll only be able to place outgoing calls.

-caller id
-caller name
 you can set here your caller id data (but it depends on the server you're
 connecting to if it will be used). 

-input device
-output device
-ring device
 here you can select among all available sound cards for input (microphone),
 output (speaker) and ring (not currently used by the plugin). 

-preferred codec
 you can select here from a list of available audio codecs, which one is
 better I don't know, it depends on your internet connection and the server
 you're using.

-denoise
-agc
-analog agc
-echo suppression
-add comfort noise
 these are filters provided by the iaxclient library. DON'T select
 echo suppression, since it doesn't work and will crash the plugin.
 Analog agc (that uses the mixer to adjust the input level) won't work if agc
 isn't selected.

-show levels
 select this option if you want to see in real time the mic level and the 
 received audio level. Note that this option burns a lot of cpu, so enable
 it only if you have enough cpu to do everything (audio coding/decoding and
 normal vdr operation).
 
-default prefix
 this is the number that will be present by default when entering the main
 menu (e.g. I'm using voipbuster, with it all calls, even local ones, have
 to be dialled as international, so I put here 0034 and I just have to enter
 the local number when calling the plugin menu). 


USAGE
===============================================================================
The main menu will show 
- a registration status line (i.e. if you are registered with the server or
  not or if is there a problem with the registration).

- a call state line (free, calling, incoming call, etc.). In case there's an
  established call you'll see the codec used and the call duration on the
  next line.

- an indication of the mic and audio level (only if selected in the setup,
  the indication is active only with an ongoing call). BE CAREFUL: if you
  don't have enough cpu it's possible that the called party will hear you
  really bad with this option enabled.

- an indication of the output volume (the plugin controls the pcm channel of
  the mixer). Using the left or right keys while on
  this line will change the volume. It should also change with the
  vol+ and vol- keys, but since I don't have those I didn't test it.
  Note that when placing or answering to a call this line will be
  automatically selected.

- a line where you can enter the number you want to dial (you can enter '*'
  and '#' by using the yellow and blue keys)

- a line for each phonebook entry (see PHONEBOOK)

To place a call, simply enter the number to dial or select one of the
phonebook entries and press the green button.

To hang-up press the red button.

To answer to an incoming call press the green button.

To reject an incoming call press the red button.

During a call, pressing the numeric keys should send the corresponding dtmf
tones (actually a dtmf command to the iax server), and you'll hear a
confirmation beep.
The yellow and blue buttons will send '*' and '#'.


INCOMING CALLS NOTIFICATION
===============================================================================
When there's an incoming call, the plugin will call repeatedly a script
"iaxphone-ring.sh". You have to write that script and put it in your path.
I'm using the "beep" program (http://www.johnath.com/beep/) to signal
an incoming call via the pc speaker, so my "iaxphone-ring.sh" looks like
this:

#!/bin/bash
exec beep -f 1000 -n -f 1500 -n -f 2000

In order to receive incoming calls, you also have to register with the server.
When you hear the speaker, you can call up the plugin main menu to either
answer or reject the call.


PHONEBOOK
===============================================================================
Each time you call the main menu, the plugin reads the phonebook from the
file "iaxphone.conf" in the plugins configuration directory. The structure
of the file is pretty simple, it's one line per phonebook entry, each with
the following format

name:number

(of course a name cannot contain ':').
You have to edit the file outside the plugin.
The number you can dial from the plugin main menu is limited, well, to
numbers, so if you need to call someone by username or url or whatever, the
only way to do it is to use the phonebook.
An iax "number" general format is

username:password@host/extension

so if the plugin encounters a complete number like this, it will contact the
specified host supplying the specified username and password.

The plugins also interprets the following formats:

extension                this is the simplest format, the configured default 
                         iax server, username and password will be used to
                         place a call

host/extension           it will try to contact "host" anonymously

username@host/extension  it will try to contact "host" using "username" but
                         with no password

host/  or
host/s                   will directly call another iax phone

