Documentation
From Ekiga
Documentation for 3.0 - WORK IN PROGRESS -
User documentation for Ekiga 3.0
Defines the function of the book. Includes navigation aids to the remaining sections of the book, such as a table of contents, or links. This section might contain a Preface.
This document aims to describe how to use Ekiga version 3.0 at his best.
TOC
Preface
Ekiga is copyrighted by Damien Sandras (<dsandras@seconix.com>) and is written mainly by himself, Matthias Schneider, Julien Puydt, Jan Schampera and Yannick Defais. To find more information about Ekiga, please visit the Ekiga Home Page. http://ekiga.org
To report a bug or make a suggestion regarding this application or this manual, follow the directions on http://gnome.org
This program is distributed 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. A copy of this license can be found at in the software Help -> About -> License, or in the file COPYING included with the source code of this program.
Ekiga is able to use modern Voice over IP protocols like SIP, and H.323.
The Session Initiation Protocol (SIP) is a protocol developed by the IETF MMUSIC Working Group and proposed standard for initiating, modifying, and terminating an interactive user session that involves multimedia elements such as video, voice, instant messaging, online games, and virtual reality. In November 2000, SIP was accepted as a 3GPP signaling protocol and permanent element of the IMS architecture. It is one of the leading signalling protocols for Voice over IP.
H.323 was originally created to provide a mechanism for transporting multimedia applications over LANs but it has rapidly evolved to address the growing needs of VoIP networks. One strength of H.323 was the relatively early availability of a set of standards, not only defining the basic call model, but in addition the supplementary services, needed to address business communication expectations. H.323 was the first VoIP standard to adopt the IETF standard RTP to transport audio and video over IP networks. H.323 is based on the ISDN Q.931 protocol and is suited for interworking scenarios between IP and ISDN, respectively between IP and QSIG. A call model, similar to the ISDN call model, eases the introduction of IP Telephony into existing networks of ISDN based PBX systems.
Introduction
Explains the application to new users. You should provide an expanded definition of the function of the application, built around illustrations and examples.
Ekiga is a free Voice over Internet Protocol -further referred as VoIP in this manual-, IP Telephony and Video-Conferencing application for Linux and other Unices (e.g BSD or OpenSolaris) and for Windows. You can place an audio and video call to a contact PC to PC, PC to phone, write an SMS, being called Phone to PC.
It supports all major VoIP features like audio and video call, call hold, call transfer, call forwarding. It also supports instant messaging.
Ekiga supports the best free audio and video codecs for a superior audio and video quality, together with echo cancellation.
Document body
Consists of several sections or chapters that provide a more detailed explanation of how to use the application. This is where you achieve completeness, telling the user how to complete all the main tasks associated with the application. Chapter headings are usually descriptive of the each topic area. Sub-headings within the chapter are usually task-oriented, so that users can quickly find information about a specific action within the topic area.
Getting started (first time Assistant)
When starting Ekiga for the first time the configuration assistant will show automatically. The Configuration Assistant is a step-by-step questionnaire that will guide you through all the steps involved in creating the basic configuration you will need to operate Ekiga. You should go through all of these steps properly, otherwise the assistant will re-appear (when it has not been completed) or Ekiga will not function appropriately (if some of your answers have not been correct). You may run the Configuration Assistant at any time from the Edit menu.
Tip | All settings can be changed via the preferences window at anytime.
Throughout the entire configuration process navigation is available at the bottom of the window. You will be able to navigate through the questions using Back, Forward and Cancel. If you hit Cancel during the setup, Ekiga will not be affected by your changes and all entered information will be discarded.
This page welcomes you to the Configuration Assistant. There is nothing to change or edit here. Press the 'Forward' button towards the bottom of the window to start the configuration.
Define your Identity
The Personal Information window requires you to supply personal information to use Ekiga. You must provide both your name and surname. This information is displayed when connecting to other audio/video applications.
Register to a VoIP service
Ekiga.net is a free VoIP services platform provided to Ekiga users allowing calls PC to PC. If you want to call other users and to be callable, you need a SIP address. You can get one from http://www.ekiga.net. Ekiga.net also offers additional services like conference rooms or online white pages. Please see http://www.ekiga.net for more information.
Follow the link given in the dialog to get an account if you do not have one, then fill in your username and password. Please press 'Forward' after having entered all required information to continue.
Ekiga Call Out Account (PC to Phone)
Ekiga can be used with several Internet Telephony Service Providers. Those providers will allow calling real phones from your computer using Ekiga at interesting rates. There is no obligation for you to use one of those commercial providers. If you need such service, we are recommending you to use the default Ekiga provider.
If you do not want to use this provider, check the box in front of "I do not want to sign for the Ekiga Call Out service" and press "Forward"
Default provider
If you want to create an account and use it to call your friends and family using regular phones at interesting rates, click the "Get an Ekiga Call Out account" link.
Once the account has been created, you will receive a login and a password by e-mail. Enter them in the dialog, and you are ready to call regular phones using Ekiga. Press "Forward".
Select your connection type
If your connection type is not mentioned in the list you should select the one closest to your network connection and adjust Ekiga manually with the preferences window (codecs section) later on. This setting will help Ekiga selecting the optimal codecs fitting your available bandwidth.
Select your audio devices
The Audio manager manages everything audio. It is dependant on the operating system on which Ekiga is running, and some operating systems offer different alternatives.
Using GNU/Linux, it is important you plug in your computer any device you want to use, like an USB headset, or a webcam. Ekiga will try its best to automatically detect them, thus allowing you to select them for your calls.
Ekiga requires audio devices to play and record sound. The audio ringing device is usually set to the internal sound card, under the name "Default", allowing you to hear a signal for incoming calls. The audio output device ouputs the incoming sound stream during a call. Please select the device that your headset or speakers are connected to; "Default" is a good choice for your internal sound card. The audio input device is where your microphone is connected to; "Default" is still a good choice for your internal sound card. These settings might be the same as the settings for the audio output if you have only one soundcard. But please note that it is also possible to record sound via another device (e.g. internal microphone in a webcam) too.
Select your Video Input Device
Please select the Video Manager from the list. It can be Video4Linux to manage webcams, or AVC / DC for Firewire cameras, or any other choice depending on the operating system on which Ekiga is running.
This step is optional and concerns users with video devices (e.g. webcams) only. If you do not have any video devices you may skip this page.
If you have a webcam or video device in the list you may select it here.
CANDIDATE FOR SUPPRESIONPlease hit the "Test Settings" button to ensure that your device works with Ekiga, if so, continue on with the Configuration.
Confirm your setup
The configuration of Ekiga is now completed. The last window only shows a short configuration summary of the settings you have chosen. Please verify that all these settings are correct. If something is incorrect you may use the 'Back' button in the lower right hand corner of the window to move to any page of the assistant and correct the mistake.
If everything is correct please press the 'Apply' button to save the configuration. The assistant will be closed and the main Window of Ekiga will now appear.
Remember, all settings can be changed via the preferences window at anytime.
Test your setup
It is generally recommended that you test your settings after having selected all the appropriate devices.
CANDIDATE FOR SUPPRESSION Please press the 'Test Settings' button on the right.
NEW If you got a SIP addresse from http://www.ekiga.net, you can call sip:500@ekiga.net which is an Echo test;
1.You should hear DO_NOT_TRANSLATE_"You're about to enter an echo test. In this mode everything you say will be repeated back to you just as soon as is it received. The purpose of this test is to give you an audible sense of the latency between you and the machine that is running the echo test application. You may end the test by hanging up or pressing the pound key."_DO_NOT_TRANSLATE
2.The echo test.
If this test was successful you can continue on to the next page REPLACE_of this documentation_REPLACE. Otherwise you should REPLACE_restart the assistant_REPLACE and test your configuration again until you have a setup that works for you.
Managing VoIP Services
You can open the accounts window by selecting Edit -> Accounts. This will open the Accounts Window. The Accounts Window will allow you to add SIP and H.323 accounts and to register to them. An account describes the user login and password parameters to register to SIP and H.323 services. Those services can be an Internet Telephony Service provider (like ekiga.net), or an IPBX (like CISCO, Nortel, or Asterisk).
Register Ekiga to a VoIP service
You can register to many VoIP service providers as you want using Ekiga.
None of those providers is mandatory to have Ekiga behaving properly. But having at least one VoIP service provider will greatly enhance the softphone Ekiga.
VoIP services can provide some very useful features to Ekiga.
- SIP Address (like sip:me@provider.net): If you want to call other users and to be callable, you're best off with a 'human readable address'(sip address), which in essence, looks just like an email address. The SIP address can be used by other users to call you. Similarly, you can use the SIP address of your friends and family to call them. For example, sip:dsandras@ekiga.net is the protocol & address used to call the author of Ekiga.
- Searchable adressbook: Most providers maintain a database registering their users and may also provide a search feature through it. Ekiga is able to tap into remote adressbooks if they use the LDAP technology.
- Conference calls: This service is in charge of collecting all audio (and possibly video) flux and mixing them before sending them back to the participants. The free PBX Asterisk can provide this feature too.
- Peering: This is the agreement between VoIP Service Providers which enables the users of one service to call users of another. This is usually implemented by dialing a special prefix number and then the number of the recipient (on the 'other' service).
- PC-To-Phone and Phone-To-PC calls: commercial providers may provide you a bridge to PSTN/Cell phones networks. The service routes the call to those networks, typically charging you for the operation.
- Voice mail: If you're not available, a caller may leave you a voice message. Ekiga tells you how many messages you have waiting. The free PBX Asterisk can provide this feature too.
- etc.
e.g. The assistant propose you 2 VoIP services:
- Ekiga.net is a free VoIP service for PC-to-PC communications. Ekiga.net allows you to have a SIP address, to search its adressbook, to setup conference calls, and to join friends using other providers with peering or ENUM.
- Ekiga Call Out is a commercial VoIP service for PC-to-Phone and Phone-to-PC communications. It also incluse sending SMS PC-to-Phone.
SCREENSHOT: account window
You can manage VoIP service providers by selecting Edit → Accounts. This will open the Accounts Window. An account describes the user login and password parameters to register to those services. Those services can be an Internet Telephony Service provider (like Ekiga.net), or an IPBX (like CISCO, Nortel, or Asterisk).
The Accounts Window will allow you to add Ekiga.net, Ekiga Call Out, SIP providers and H.323 providers accounts and to register to them.
Automated registration
Ekiga feature automated registration to your services providers. If you choosed to use Ekiga.net or Ekiga call out whitin the assistant, Ekiga will try to automatically register to them at startup. If later you want to add another VoIP service account, you'll have by default the option for Ekiga to automically register to it while creating this account under the label "Enable account" ass seem in [link the relevant part of the doc for account creation]
Manual registration
At any time you can manually registed and unregister to a VoIP service: in the Accounts Window (Edit → Accounts), you can check (register) or uncheck (unregister) the box in front of the account name.
Add an Ekiga.net account
Add an Ekiga Call Out account
Add a SIP account
To add a SIP account, simply click on Account -> New SIP Account. A dialog will appear and allow you to enter several parameters:
UNCLEAR_
- Name: You can enter the account name.
- Host: The registrar to which you want to register. This is usually an IP address or an host name that will be given to you by your Internet Telephony Service Provider, or by your administrator if you are trying to register to a SIP IPBX.
- User: You can enter your login.
- Authentication User: If it is different from the user parameter you provided above. In that case, the user field will be used to control the outgoing identity for the account you are adding, while the login will be used during the authentication phase.
- Password: You can enter your password
- Registration Timeout: The timeout after which the registration should be updated. NEW_3600 is default._NEW
Tip | Ekiga will do a best guess concerning the identity that will be used when calling out. Sometimes, you will need to force that identity. You can do this by specifying the identity in the User field. e.g.: dsandras@ekiga.net to force dsandras@ekiga.net to be used as outgoing identity for that account.
REPLACE_Those_REPLACE parameters, like the Registrar, User and Password, will be given to you by the ITSP you are using or by your administrator.
_UNCLEAR
Add an H.323 account
Managing contacts
Add a contact to your contact list (Roster)
SCREENSHOT POPULATED ROSTER
Remove a contact from your contact list (Roster)
Group contacts in your contact list (Roster)
Network Neighbours
Ekiga is also able to detect other Ekiga users on the LAN using the Bonjour technology popularized by Apple (tm). That supposes you have a local mDNSResponder daemon running on your computer.
Local Roster
CANDIDATEFORSUPPRESSION_you can edit the groups your users belong to using the User Properties dialog from the main menu or from the right-click menu, or using drag-and-drop between groups.
Search a contact in the Local Address Book
To open the Address Book, select Tools -> Find Contacts and the Ekiga Addressbook window should appear. To your left there will be a list dialog showing the LDAP servers as well as a list of local Address Books. The defaults are the Ekiga white pages, and the "personal" address book from Novell Evolution if you use the GNOME desktop, or the "personal" address book from KAddressBook if you use the KDE desktop.
To refresh the list of users for a specific address book, simply click the Find button. It will search for all users in that address book.
CANDIDATEFORSUPPRESSION_You can contact people by double clicking on their highlighted field. You can also Drag-and-Drop to call a specific party by selecting the highlighted field and dragging it into the Main Window.
You can call a cell phone from local address book if it was entered using Evolution
Add a contact to your contact list from a local address book
IMPOSSIBLE
Add a new contact to your local address book
Ekiga is able to bookmark contacts in the local address book, shared with the GNOME based Novell Evolution suiteNEW_, or the KDE based KAddressBook._NEW
To add a contact to one of your local address books, simply select the address book you wish to add the contact and select Action -> New Contact. The option of adding a New Contact will appear and you may now enter his name and VoIP URI as well as other settings. After complete select 'OK' and now your contact has been added. You can only add contacts to local address books. The contact parameters can be changed at any time by selecting Action -> Edit when the contact is highlighted.
Remove a contact from your local address book
He can also be deleted by selecting Action -> Remove.
Search in a remote Address Book (LDAP)
Ekiga is able to use several types of address books, allowing to search for remote contacts, and bookmark local contacts. The most common address book type is the LDAP directory where you can find information about registered users. Ekiga is able to browse any LDAP directory and use a specific attribute as calling URI. For example, you could have an LDAP directory in your company, with a specific attribute containing the local extensions of all your colleagues. Ekiga is able to use such an LDAP directory. Simply select in File -> New Address Book, and choose remote LDAP as type.
Search in the Ekiga White Pages
In certain cases you will want to search specifically for a person name, his or her call URI, or the location in the Ekiga white pages. The address book window allows you to apply filters when searching for contacts.
CANDIDATEFORSUPPRESSION_Tip | The Ekiga white pages will allow you to look for users in your region. It returns a limited number of results corresponding to your search. If the user is associated to a red icon, it means that he is online. If he is associated to a greyed out icon, it means he is offline. You can then add him to your personal address book to call him later.
Add a contact to your contact list from the Ekiga White Pages
You can also add a contact NEW_in the roster_NEW from the white pages (or any other local or remote address book)
CANDIDATEFORSUPPRESSION_by selecting the highlighted contact and dragging him to the specific local address book you wish to add him to or
by selecting Action -> Add To Local Roster when selecting that contact.
Add a remote address Book (LDAP)
To add an address book, select Tools -> Find Contacts. The Address Book window will appear. You then select Address Book -> Add an LDAP Addressbook.
Enter the server name.
Enter the name, the various parameters and select 'OK' and the new address book should now appear in the address books list.
If you do not know what parameters to use for a remote LDAP address book, please ask them to your administrator.
The address book parameters can be changed at any time by selecting Action -> Properties when the address book is highlighted.
Remove a remote address Book (LDAP)
It can also be deleted by selecting Action -> Remove.
Managing calls
Ekiga supports different policies for incoming calls. Per default it displays a popup window which allows you to decide whether you want to refuse or accept the request for an incoming call.
FIXME Furthermore Ekiga offers REPLACE_two_REPLACE modes that override this behaviour: Do Not Disturb, and Forward. They can be activated from the the REPLACE._Main Window_REPLACE
Set your status
Online
Away
Do Not Disturb
FIXME If this mode is enabled Ekiga refuses all incoming requests and only allows outgoing calls. You are not able to receive any call and do not notice if another user tries to contact you except when looking at the Calls History.
This mode can be enabled by selecting Do Not Disturb in the main window.
Define a custom message
Chat with a contact
IM
Read your contact status
Send instant messages
Ekiga allows you to send instant messages to remote users provided that you know their URI.
CANDIDATEFORSUPPRESSION You can by opening the chat window by selecting Tools -> Chat Window.
To send a text message to an user, _[part REMOVED]_highlight an user, and select REPLACE_Message_REPLACE. The chat window will appear and allow you to do a conversation with the selected remote user.
Tip | You can also exchanges text messages with H.323 Ekiga users, but only while being in a call.
CANDIDATEFORSUPPRESSION To do this, simply click on the new tab icon, and a new tab will automatically be created allowing a conversation with the user you are in a call with.
Use smileys
Call a contact
Ekiga supports several actions which can be performed when in a call. These actions enable you to control active sessions.
Select an account for a call
Call on internet (PC to PC)
If you want to call other users and to be callable, you need a SIP address. You can get a SIP address from http://www.ekiga.net as described above.
The SIP address can be used by other users to call you. Similarly, you can use the SIP address of your friends and family to call them. You can for example use sip:dsandras@ekiga.net to call the author of Ekiga.
You can use the online address book of Ekiga to find the SIP addresses of other Ekiga users. It is of course possible to call users who are using another provider than ekiga.net. You can actually call any user using SIP software or hardware, and registered to any public SIP provider
If you know the URI address of the party that you wish to call, you may enter that URI into the sip: input box at the top of the screen and press the Connect button; eg: sip:foo@ekiga.net and pressing the Connect button would call the user at that address. With the default setup, you can simply type sip:foo to call user foo@ekiga.net.
Tip | Ekiga also supports H.323 and as such can call any H.323 software or hardware. Please refer to the section REPLACE_"Understanding VoIP addresses"_REPLACE to learn more about the various types of URIs that can be used to call remote H.323 and SIP users.
Call out (PC to Phone)
Ekiga can be used with several Internet Telephony Service Providers. Those providers will allow calling real phones from your computer using Ekiga at interesting rates. We are recommending you to use the default Ekiga provider.
Default provider
If you want to create an account and use it to call your friends and family using regular phones at interesting rates, go in the Tools menu, and select the "PC-To-Phone Account" menu item. A dialog will appear allowing you to create an account using the "Get an Ekiga PC-to-Phone account".
Once the account has been created, you will receive a login and a password by e-mail. Simply enter them in the dialog, enable "Use PC-To-Phone service", and you are ready to call regular phones using Ekiga
Dial a number
With the default setup, you can simply use sip:003210444555 to call the real phone number 003210444555, 00 is the international dialing code, 32 is the country code, 10444555 is the number to call.
Send SMS
Other providers
Call in (Phone to PC)
Ekiga can be used to receive incoming calls from regular phones.
Default Provider
To allow this, you can simply login to your PC-To-Phone account using the Tools menu as described above, and buy a phone number in the country of your choice. Ekiga will ring when people will call that phone number.
Other providers
You can actually use any H.323 or SIP ITSP provider, including your own PBX at work. However we recommend using the integrated provider.
End a call
The communication to the remote user can be ended by selecting Call->Disconnect.
Hold a call
You can hold a remote party call by selecting Call->Hold. This effectively pauses Video and Audio transmission, to continue transmission again you select Call->Retrieve Call and Video and Audio Transmission will begin again.
Mute Audio
This effectively prevents all Audio communication to your respective party.
Suspend Video
This effectively prevents all Video transmission to your respective party.
Transfer a call
Transferring the remote party: You can transfer the remote user to another H.323 or CALLTO URI by using the appropriate menu entry in the Call menu or by double-clicking on an user in your address book, or in the calls history.
Tip | All URIs supported by Ekiga (SIP, H.323, CALLTO and Speed Dials) can be used for call transfer.
Forward incoming calls
Ekiga has the ability to forward calls to another host. Which allows you to configure Ekiga to forward all incoming calls to a specified URI. Furthermore it is able to forward calls interactively when you do not answer the call after a configurable amount of time or when you are busy.
Call Forwarding can be configured through the preferences window. Notice that you need to specify an URI where to forward calls in the preferences to be able to activate that option. Open the preferences window by choosing Edit -> Preferences in the main window and select Call Options on the left. You will now see the appropriate section. It contains three checkboxes for the three cases described above. The IP address/hostname of the host the calls shall be forwarded to can be configured separate in SIP Settings for SIP and accordingly in H323 Settings for H323.
Message Waiting Indications
Calls History
The Calls History window stores information (date, duration, URI, Remote user) about all outgoing and incoming calls. They are divided into three groups "Received calls", "Placed calls" and "Unanswered calls".
Received calls contains all incoming calls which were accepted by Ekiga. NEW_It is preceded by this icon SCREENSHOT GREEN ARROW RIGHT_NEW
Placed calls keeps track of all attempts - successful or not - to call another user.NEW_It is preceded by this icon SCREENSHOT GREEN ARROW LEFT_NEW
Unanswered calls shows incoming calls which timed out or were rejected (if Do Not Disturb is enabled, for instance) by Ekiga.NEW_It is preceded by this icon SCREENSHOT GREY ARROW RIGHT_NEW
Tip
|
REPLACE_Right click_REPLACE on a row in the Calls History will NEW_allow to_NEW call back the selected user, or transfer any active call to that userNEW_, or add the selected contact to the roster_NEW.
CANDIDATEFORSUPPRESSION_Notice that you can also drag and drop entries from the Calls History into the Address Book to store contact information.
This information can be accessed by opening REPLACE_View_REPLACE->Calls History and by switching between the three tabs.
Missing calls
Dialpad
Monitor a call
SCREENSHOT Main Window while calling, the mouse pointing the status bar
To view the statistics, please REPLACE_point with the mouse the status bar of Ekiga at the bottom of the main window.
The statistic REPLACE_show_REPLACE the network traffic caused by Ekiga.
CANDIDATEFORSUPPRESSION It draws a graph for each RTP stream. This means that - if audio and video are enabled in Ekiga and the client of the remote party - you will see four different graphs. (incoming audio stream, incoming video stream, outgoing audio stream, outgoing video stream)
- Lost packets: The percentage of lost packets, ie of packets from the remote user that you did not receive. A too high packets loss during the reception can result in voice and/or video distortion and is usually caused by a bad network provider or by settings requiring much bandwidth.
- Late packets: The percentage of late packets, ie of packets from the remote user that you received but too late to be taken into account, Ekiga being sending and receiving real-time video and audio.
- Round-trip delay: The required time for a packet to arrive at its destination and come back. You can see the Round-Trip delay during a call as a connection quality indicator together with the Lost and Late packets statistics.
- Jitter buffer: The Jitter buffer is the buffer where received sound packets are accumulated. When the buffer is full, then the sound is played. If your network is of bad quality, then you need a big jitter buffer, ie a big delay before sound is played back, because you need more time before being able to play audio back.
Configuration
Ekiga supports several audio and video codecs. It includes codecs with excellent quality as well as codecs with medium to good quality. The higher the quality of a codec, the more bandwidth NEW_or CPU power_NEW it requires. REPLACE_The first time Assistant define an_REPLACE initial configuration of Ekiga so that it chooses the optimal codec suited to your network connection.
Adjust Audio
Adjust audio input and output volume
Choosing the right audio device
Select the best quality/bandwidth ratio for audio
The Ekiga audio codecs table in the preferences permits you to change the codecs order as well as disabling the codecs you don't want to use. Each codec has strong and weak points. For example, G.711 will give the best voice quality but will use the most bandwidth while SPEEX will give an average voice quality but requiring a very low bandwidth usage. Notice that there are two versions of SPEEX, one of them is SPEEX WideBand. You can see that to the 16 kHz clock rate.
When you reorder the codecs, you are reordering the local capabilities table, ie the codecs you will use for sending. You will always transmit audio using the first codec in the table that is in common with the remote user. The remote user will transmit audio using the first codec in his table that is common with you.
You can force the use of a specific codec by disabling all other codecs, but it will result in failed calls if the remote user doesn't allow that specific codec. The best is to put your prefered codecs at the top of the list so that you always transmit with them if the remote user allows it and to disable the codecs that you don't want to use for transmission and reception.
Adjust Video
Adjust brightness, whiteness, color and contrast of your video input device
Choosing the right video device
Select the best quality/bandwidth ratio for video
Moreover, video codecs can adapt their quality to the available bandwidth. This option is necessary in the initial configuration of Ekiga so that it chooses the optimal codec suited to your network connection and so that it adjusts the video quality settings.
Activate the video support in calls
Test your webcam
Controlling the Video Bandwidth
Ekiga is using a best-effort algorithm to maintain a low bandwidth when transmitting video. You can adjust the video quality settings following you prefer to have a good frame rate, or a good picture quality. It will permit Ekiga to dynamically adjust the video bandwidth and the number of transmitted images per second during a call while trying to respect the requested video bandwidth.
Notice that the algorithm is a best-effort algorithm, which means that if you specify too low video bandwidth settings, it can be impossible to respect them. However, if the video bandwidth permits to transmit with a better quality, or faster than the requested values, then Ekiga will dynamically increase them so that the quality and the framerate are always the best possible.
Choosing a higher framerate and a lower quality will have the same result in terms of video bandwidth than choosing a higher quality with a lower framerate. It depends if you prefer using your bandwidth to transmit more lower quality images or fewer big quality images.
Send a picture instead of video to your contact
SIP preferences
Outbound Proxy
The outbound proxy is the SIP proxy that will relay your calls. The behavior of a SIP proxy is similar to the behavior of an HTTP proxy, ie some entity that issues the requests on your behalve and proxies the streams.
Forward URL
The URI to which SIP incoming calls should be forwarded if configured in the preferences.
H323 preferences
Default gateway
The default gateway is the H.323 gateway to use when doing calls. For example, if you are calling h323:123443 with a default gateway set to foo, gateway foo will dial 123443 on your behalve. Usually, you will be registered to a gatekeeper, and gateway is not used.
Forward URI
The URI to which H.323 incoming calls should be forwarded if configured in the preferences.
Advanced Settings
Ekiga permits a fine control of the H.323 settings in the Advanced H.323 Settings section of the preferences. You can enable H.245 Tunneling, Early H.245 and Fast Start.
H.245 Tunneling
H.245 Tunneling is the encapsulation of H.245 messages within H.225/Q.931 messages (H.245 Tunneling). If you have a firewall and enable H.245 Tunneling, there is one less TCP port that you need to allow for incoming connections.
Early H.245
This enables H.245 early in the setup and permits to achieve faster call initiation.
Fast Start
Fast Connect is a new method of call setup that bypasses some usual steps in order to make it faster. In addition to the speed improvement, Fast Connect allows the media channels to be operational before the CONNECT message is sent, which is a requirement for certain billing procedures. It was introduced in H.323 version 2.
Using Ekiga with Audio Servers
Windows: Direct Sound
GNU/Linux: ALSA, Pulse Audio, OSS
FreeBSD: OSS
Solaris: OSS
Using Ekiga with Routers and firewalls
NAT traversal
Ekiga has advanced methods to allow the traversal of various NAT types. There is still a type of NAT, the Symmetric NAT, which cannot be traversed without exterior help, a proxy. If Symmetric NAT is found, ekiga will register, but no call can be made. Right after the registration, it shows (in the current version) the message "Bad NAT type" in the terminal. Upon calling, it gives the "Abnormal call termination" error. With "-d 5" you will see a message like this:
2008/07/24 10:46:45.008 0:02.777 StunDetector:0x41b1d950 OPAL STUN server "stun.voxgratia.org" replies Symmetric NAT, external IP X.Y.Z.T
More information about symmetric NAT: Symmetric NAT means that it's not possible de guess what ports will be used. There is no solution in this case, except using an external proxy. Such proxies use VERY high bandwidths. (Skype for example avoids this problem by using users with public IP addresses themselves as proxies.)
GNOME
The main port listening for incoming connections in Ekiga for SIP is port 5060 (UDP), while 1720 (TCP) is used by H.323. To change those ports you need to load "gconf-editor". Open gconf-editor, select apps from the left hand side menu and then select Ekiga. Then select "sip" or "h323", it should give you a list in the corresponding window to your right. Select listen_port and change it to your desired value. You can also change the UDP/RTP port ranges.
1. The "listen_port" value is the port Ekiga will listen for incoming connections on. It is different for SIP and H.323.
2. The "rtp_port_range" value is the range of UDP ports that Ekiga will use for RTP (audio and video communication channels). Ekiga needs to be restarted for the new values to take effect.
3. The "udp_port_range" value is the range of UDP ports that Ekiga will use for SIP signalling or when registering to H.323 gatekeepers.
4. The "tcp_port_range" value is the range of TCP ports beside the listen_port that Ekiga will use for the H.245 channel with the H.323 protocol. That port range is not used by SIP. It is not used either when H.245 Tunneling is enabled, which is in general always the case, except when calling old H.323 implementations like Netmeeting.
Troubleshooting
Troubleshooting is covered in more detail in the Troubleshooting Section in the wiki.
Error messages in Ekiga
These are the error message Ekiga presents. OPAL sends a numeric code to Ekiga and Ekiga presents these phrases to the user. The two messages with opal codes of n/a are produced internally by Ekiga.
It has been noted that Ekiga cannot offer more details than it gets from OPAL.
Ekiga OPAL Internal Message Code Parameter Address incomplete 484 Failure_AddressIncomplete Alternative service 380 Redirection_AlternativeService Ambiguous 485 Failure_Ambiguous Bad event 489 Failure_BadEvent Bad gateway 502 Failure_BadGateway Bad request 400 Failure_BadRequest Busy everywhere 600 GlobalFailure_BusyEverywhere Busy Here 486 Failure_BusyHere Conflict 409 Failure_Conflict Decline 603 GlobalFailure_Decline Does not exist anymore 604 GlobalFailure_DoesNotExistAnywhere Extension required 421 Failure_ExtensionRequired Forbidden 403 Failure_Forbidden Globally not acceptable 606 GlobalFailure_NotAcceptable Illegal status code n/a IllegalStatusCode Internal server error 500 Failure_InternalServerError Interval too brief 423 Failure_IntervalTooBrief Length required 411 Failure_LengthRequired Loop detected 482 Failure_LoopDetected Message too large 513 Failure_MessageTooLarge Method not allowed 405 Failure_MethodNotAllowed Moved permanently 301 Redirection_MovedPermanently Moved temporarily 302 Redirection_MovedTemporarily Multiple choices 300 Redirection_MultipleChoices Not acceptable 406 Failure_NotAcceptable Not acceptable here 488 Failure_NotAcceptableHere Not found 404 Failure_NotFound Not implemented 501 Failure_NotImplemented Payment required 402 Failure_PaymentRequired Proxy authentication required 407 Failure_ProxyAuthenticationRequired Request entity too big 413 Failure_RequestEntityTooLarge Request pending 491 Failure_RequestPending Request terminated 487 Failure_RequestTerminated Request URI too long 414 Failure_RequestURITooLong Server timeout 504 Failure_ServerTimeout Service unavailable 503 Failure_ServiceUnavailable SIP version not supported 505 Failure_SIPVersionNotSupported Temporarily unavailable 480 Failure_TemporarilyUnavailable Timeout 408 Failure_RequestTimeout Too many hops 483 Failure_TooManyHops Transport error n/a Local_BadTransportAddress Unauthorized 401 Failure_UnAuthorised Undecipherable 493 Failure_Undecipherable Unsupported media type 415 Failure_UnsupportedMediaType Unsupported URI scheme 416 Failure_UnsupportedURIScheme Use proxy 305 Redirection_UseProxy
Glossary
Defines specific terms in the book. You do not need to define terms that are in the http://www.bartleby.com/61/.
VoIP
NAT
SIP
H.323
Appendices
Contain additional notes about related topics that are not directly explained in the document body.
Related Softwares
IPBX
* Asterisk PBX: http://asterisk.org
SIP
* SIP Express Router: http://www.iptel.org/ser
H.323
* OpenH323 Gatekeeper: http://www.openh323.org * GNU Gatekeeper: http://www.gnugk.org * OpenH323 Proxy: http://openh323.sourceforge.net * H323 - ISDN Gateway: http://www.telos.de/linux/H323/
Conferencing/VoIP Software
* OpenMCU: http://www.openh323.org
Similar Clients
* XTen: http://www.xten.com * SJPhone: http://www.sjlabs.com/ * OpenPhone: http://www.openh323.org * Netmeeting: http://www.microsoft.com
Understanding VoIP addresses
SIP addresses
SIP URIs are formatted as such "sip:user@[host[:port]]"
This permits you to call the given user or extension on the specified SIP proxy: sip:jonita@ekiga.net
H.323 addresses
H.323 URIs are formatted as such "h323:[user@][host[:port]]"
This permits you to:
* Call a given host on a port different from the default port which is 1720: h323:seconix.com:1740 * Call a given user using their respective alias if registered to a gatekeeper: h323:jonita * Call a given phone number if you are registered to a gatekeeper for a PC-To-Phone provider, or if that user has an ENUM record associated to an H.323 URI: h323:003210111222 * Call a given user using their alias through a specific gateway or proxy: h323:jonita@gateway.seconix.com * Call an MCU and join a specific room: h323:myfriendsroom@mcu.seconix.com
CALLTO addresses
Callto URIs are formatted as such "callto:[user@][host[:port]]"
Callto URIs and H.323 URIs are formatted exactly the same except however callto URIs also support ILS lookups directly: callto:ils_server/user_mail.
CANDIDATEFORSUPPRESSION_For example, calling callto:ils.seconix.com/joe.user@somedomain.com will look for the user with the joe.user@somedomain.com email address on the ILS server ils.seconix.com and proceed to initate a call.
Technical Specifications
SIP
List the RFCs
Network transversal: STUN
Free codecs Plugins Vidéo: H263, H264 Plugins Audio: G729, iLBC
H323
List the RFCs
Free codecs Audio: G729, iLBC
IM: SIP/SIMPLE
Plug n'play using a local network: ZeroConf/Bonjour
codecs
audio
Video
LDAP support
ENUM support
API for devices support
Audio: OSS, ALSA, Direct audio
Video: V4l, V4l2, FireWire, DirectX
GNOME integration
Evolution address book
SIP URI in GNOME
Configuration storing (GConf daemon)
KDE integration
KAdressBook
SIP URI in KDE
Configuration storing
Windows integration
SIP URI in Windows
Configuration storing
Index
Provides keyword links to specific concepts in the book. Follow the guidelines in this guide to create an effective index.
