Overview

Description

Linphone has inside a separation between the user interfaces and the core engine, allowing to create various kinds of user interface on top of the same functionalities.

The user interface frontends:

Gtk+/glade interface

The console interface (linphonec, linphonecsh)

The iPhone application built in objective C

The Android application running in java

Liblinphone, the core engine: this is the library that implements all the functionalities of Linphone. Liblinphone is a powerful SIP VoIP video SDK that anyone can use to add audio or video call capabilities to an application. It provides a high level api to initiate, receive, terminate calls.

Liblinphone relies on the following software components:

Mediastreamer2, a powerful multimedia SDK to make audio/video streaming and processing.

oRTP, a simple RTP library.

belle-sip the SIP user agent library.

Liblinphone and all its dependencies are written in pure C.

Architecture

Console tools

Linphonec is a command line interface that can use readline on linux to get completion, history, such as bash.Linphonecsh is another command line tool to remotely control a linphonec daemon. Unlike linphonec, linphonecsh immediately exits once the command is executed.See the documentation tab for more information.

For those who are behind a proxy :You can change the access method from git:// to http:// as follows:Normal git access:git clone git://git.linphone.org/msilbc.gitBehind a proxy, use http access:git clone http://git.linphone.org/git/msilbc.git

Daily builds (testing)

Every day some binary packages generated from the current git state are uploaded at http://www.linphone.org/snapshots . It is worth to visit it if you want to test and see the latest changes, especially when a long time has elapsed since the last official stable release. These snapshots are generated automatically and not tested, some features might be broken from time to time.

Documentation

Documentation

Instructions

Linphone command line tools

Linphonec

Linphonec is a terminal based version of linphone that reads commands from the user prompt.

Example:

Start linphonec in a terminal$ linphonecReadyWarning: video is disabled in linphonec, use -V or -C or -D to enable.Place an outgoing calllinphonec> call sip:594305005@someproxy.netAlternatively, if someproxy.net is your default proxy configuration (entered via 'proxy add' command), you call simply like thislinphonec> call 594305005Terminate a calllinphonec> terminateAt any time you can list available commands using 'help':linphonec> help

Commands are:

help Print commands helpcall Call a SIP urichat Chat with a SIP uriterminate Terminate the current callanswer Answer a callautoanswer Show/set auto-answer modeproxy Manage proxiessoundcard Manage soundcardswebcam Manage webcamsstaticpic Manage static pictures when nowebcamipv6 Use IPV6refer Refer the current call to the specified destination.nat Set nat addressstun Set stun server addressfirewall Set firewall policycall-logs Calls historyfriend Manage friendsplay play from a wav filerecord record to a wav filequit Exit linphonecregister Register in one line to a proxyunregister Unregister from default proxyduration Print duration in seconds of the last call.status Print various status informationports Network ports configurationspeak Speak a sentence using espeak TTS enginecodec Audio codec configurationvcodec Video codec configurationec Echo cancellationmute Mute microphone and suspend voice transmission.unmute Unmute microphone and resume voice transmission.nortp-on-a Set the rtp_no_xmit_on_audio_mute configuration parameter

Type 'help <ltcommand>' for more details.

Linphonecsh - control a linphonec daemon

Linphonecsh is a console utility to send non-blocking commands to an instance of linphonec runnning in the background.Here is an example to run within your favourite shell and terminal:

This feature is still being developed, stay connected to svn if you use it !What could be the applications of this tool ? For example:

run VoIP calls from scripts

from web cgi pages

from javascript in a browser window...

Configuration file documentation

Linphone has a linphonerc configuration file in which all SIP, RTP, sound, video settings are read and stored. By default no configuration file is required and linphone always generates a default one at first startup.Most of the parameters are used internally by accessors of liblinphone (ex: linphone_core_set/get_audio_port()) and thus do not need to be accessed directly by editing the config file.However some parameters are related to fine grained settings: noise gate, echo canceler parameters, echo limiter etc.Follows here a description of sound related tunables and a documented linphonerc config file with all settings.

#Use this when you have a fixed latency in the sound hardware.#This allows to reduce the tail length of the echo canceller, which speeds up convergence#and reduces complexity of computations.ec_delay=0

#Tail length of echo canceller in milliseconds.#Ideally it should be no more than the expected duration of the echo.ec_tail_len=60

#Frame size for AU-MDF echo canceller algorithm#This is a parameter internal to the echo canceller, recommended is too keep to its default value.ec_frame_size=128

Echo limiter

The echo limiter is an algorithm that consists in lowering the gain of the mic input when the speaker is talking. Combined with the noise gate (see next section) it gives good results when the echo canceller no more works, because of non linear distorsion (saturation) of the echo path.Its drawback is that it turns the call in a kind of automatic half-duplex mode, which makes impossible to interrupt the person who is talking.

[sound]#Enables echo limiter#this basically consists in lowering the mic input (in software)#when the speaker level is above a certain threshold#the attenuation is made proportionnal to the speaker detected levelecholimiter=0

#el_speed parameter: gain changes are smoothed with a coefficent#el_speed is this coefficient. It's a value between 0 and 1#0.1 is already very fast, 0.001 is very low#default value is 0.03#recommendation is to keep it unchangedel_speed=0.03

#el_thres parameter#Threshold above which the system becomes active.#It is a normalized power, between 0 and 1.#Default value is 0.1# A smaller value can be better.el_thres=0.1

#el_sustain parameter#Time in milliseconds for which the attenuation is kept unchanged after #resuming from speech to silence on the network->speaker channel.#This is a very important parameter that needs to be adjusted#to take in account the latency of the sound card/driver.#Indeed when the echo limiter sees there is no more energy going to the #speaker, there can be still some audio buffers pending to be played#in the audio driver. These buffers are out of control of the application#and will generate echo as they are non-silence.#The purpose of the parameter is to keep the mic attenuated#for some time until the echo of these buffer is finished.#100 ms is a reasonable value to start, can be higher depending#on the hardware.el_sustain=100

Noise gate

The goal of the noise gate is to remove (or attenuate a lot) the background noise heared by the microphone. Noise and speech are distinguished using an energy threshold. The use of the noise gate can prevent feedback to produce between two devices running linphone.

[sound]#The noise gate is located just after mic input#Tells whether noise gate is active:noisegate=0

#Noise gate threshold in linear power between 0 and 1:#Above this threshold the noise gate becomes bypass.ng_thres=0.05

#Noise gate's floorgain: gain applied to the signal when its energy is below the threshold.#It is expect to be low so that noise is attenuated.ng_floorgain=0.0005

Equalizer

A parametric equalizer can be used to recover from speakers with bad spectral response. The frequency response of the equalizer is entirely configurable.

[sound]#equalizer: it is located before speaker output#Tells whether equalizer is active.eq_active=0

#equalizer gains.#It is a list of triplets ::#for example:#eq_gains=300:0.1:100 700:0.2:250

Miscellaneous audio parameters

#static software gain (log scale) to be applied to signal sent to speakerplayback_gain_db=0.0

#Enable or disable DC removal of mic input:dc_removal=0

Linphonerc sample file documented

##section relative to sound settings[sound]#sound device name used for playback, as listed in linphonec by "soundcard list"playback_dev_id=ALSA: default device#sound device name used for ringing, as listed in linphonec by "soundcard list"ringer_dev_id=ALSA: default device#sound device name used for capture, as listed in linphonec by "soundcard list"capture_dev_id=ALSA: default device#Alsa special device name# This option allows to specify a special ALSA card (as defined in ALSA asoundrc config files)# to be used by linphone. This card can then be referred by playback_dev_id, ringer_dev_id, capture_dev_id options.# Use this if you are able to understand asoundrc syntax and you know what you are doing.#alsadev=#wav file to play to advertise remote ringingremote_ring=/usr/local/share/sounds/linphone/ringback.wav#wav file to play to advertise incoming callslocal_ring=/usr/loca/share/sounds/linphone/rings/bigben.wav#turn on/off echo cancellationechocancellation=1#Expected delay of echo in milliseconds#Use this when you have a fixed latency in the sound hardware.#This allows to reduce the tail length of the echo canceller, which speeds up convergence#and reduces complexity of computations.ec_delay=0#Tail length of echo canceller in milliseconds.#Ideally it should be no more than the expected duration of the echo.ec_tail_len=60#Frame size for AU-MDF echo canceller algorithm#This is a parameter internal to the echo canceller, recommended is too keep to its default value.ec_frame_size=128#static software gain (linear scale) to be applied to microphone signalmic_gain=1.0#static software gain (log scale) to be applied to signal sent to speakerplayback_gain_db=0.0

##Video settings[video]#Size of sent video among these names: QCIF, QVGA, CIF, VGA, SVGAsize=cif#Whether video is enabled:enabled=1#You can refine whether it is enabled for display or capture or bothdisplay=1capture=1#Show local preview between calls.show_local=1#Show local view during calls, in a corner of the video windowself_view=1#Webcam name for capturedevice=V4L2: /dev/video0

##Network settings[net]#Estimated download bandwidth in kbit/sdownload_bw=1024#The bandwidth settings are used to control the bitrate of video (and sometimes audio) encoder, as well#as limiting the size or fps of the sent video.#Estimated upload bandwidth in kbit/supload_bw=1024#Firewall policy:# 0: assume there is no nat# 1: use firewall address supplied in "nat_address" item (discouraged)# 2: use STUN to discover its own public IP address and ports# 3: use ICE.

firewall_policy=0#Network's Maximum Transmission Unit# Use 0 to allow automatic discovery, otherwise set to a number of bytes.# This parameter is only meaningful with video streams for which RTP packets are big.mtu=0#STUN server address to use when in firewall_policy=2stun_server=stun.ekiga.net#Firewall address to use when in firewall_policy=1nat_address=80.112.33.11

##SIP settings[sip]#SIP port usedsip_port=5060#Discover automatically local IP addressguess_hostname=1#Contact address when no proxy is used# The host port is always overriden at runtime if guess_hostname # is set to 1.contact="Bob" #Incoming call answering timeoutinc_timeout=15#Use SIP INFO to send DTMFs (digits)use_info=0#Use RFC2833 (out of band DTMFs) to send digitsuse_rfc2833=0#Use IPv6. caution: it is exclusive with IPv4. use_ipv6=0#Send registers only when network is upregister_only_when_network_is_up=1#Default proxy to use (the number is the index of the proxy configuration in this config file)# Use -1 for no proxy.default_proxy=-1#Keepalive period in milliseconds for sending out SIP UDP keepalive to the proxies.keepalive_period=10000#When answering to SDP offers, select only one codec, #instead of replying with all matching codecs.only_one_codec=0#Send an OPTIONS message before doing outgoing calls#This is used by Linphone to workaround some NAT problems inherent to SIP.#This is highly recommended.ping_with_options=1#Network state automatic monitoring# When set to 1, linphone will periodically monitor the network state (by checking whether it is possible# to reach the internet).# When the operating system has callbacks to notify such information, you can use # linphone_core_set_network_reachable() to notify the core, in which case no network monitoring will be done internally.auto_net_state_mon=1

## Audio codec descriptions# These sections are named audio_codec_X, where X is a number.# This number identifies the position of the described codec# in the core's audio codec list.[audio_codec_0]# sub-mime type as defined in RFC3551 or codec's specific RFC:mime=speex# RTP clock-rate as defined in RFC3551 or codec's specific RFC:rate=8000# Tells whether is codec is enabledenabled=1# Fmtp (format parameters) string to be sent in SDP for this codec, which# corresponds usually to what we are prefering to receive.# RFC3551 or codec's specific RFC describes the allowed parameters.recv_fmtp=vad=on

## Video codec descriptions# These sections are named video_codec_X, where X is a number.# This number identifies the position of the described codec# in the core's video codec list.[video_codec_0]# sub-mime type as defined in RFC3551 or codec's specific RFC:mime=H264# RTP clockrate as defined in RFC3551 or codec's specific RFC, usually 90000 for video payloads.rate=90000# Tells whether the codec is enabledenabled=1# Fmtp (format paramters) string to be sent in SDP for this codec, which# corresponds usually to what we are prefering to receive.recv_fmtp=packetization-mode=1## SIP Proxy configuration# Like with audio_codec, it is possible to define several proxy configuration in the# form of [proxy_X] section, where X is a number.

[proxy_0]#SIP address of the proxyreg_proxy=sip:example.net#SIP identity for which you are known on this proxy:reg_identity=#Expiration period of the registration in secondsreg_expires=3600#Whether to send a register or notreg_sendregister=0#Route: SIP server address to send all outgoing SIP requests#It is usually left blank, otherwise it is commonly used to specify this proxy #must be used as an outbound proxy, for example:# reg_route=sip:example.net reg_route=#Send a PUBLISH request to the proxy to notify about presence information (online, busy, out to lunch)publish=0#whether "+" in phone numbers should be replaced by 00dial_escape_plus=0#Phone number prefix to be applied to entered destinations.#Example: prefix=+33prefix=

## Authentication information# Similarly, several auth_info_X can be defined# Authentication information is kept distinct from proxy information# because there can be authentication challenges from proxies or user# agents even if we are not registered to any proxy.[auth_info_0]#SIP usernameusername=bob#sip userid (usually the same as username, don't specify unless you know what you are doing)userid=bob#password associated with above username, userid and realmpasswd=mysecret#SIP authentication realm (= authentication domain), can be left empty if realm is not known.realm="example.net"###SIP favourite contacts (friends, buddies...)# Again it is represented as a family of [friend_X] sections.[friend_0]#SIP address of buddyurl=Alice #Policy for incoming SUBSCRIBEs for presence. Can be:# accept : we accept to share our presence status with this person# deny : we don't want to share our presence status with this personpol=accept# Send SUBSCRIBEs for presence to this person, so that# we are notified about her presence information.subscribe=1

###Other stuff stored in config files that are not configuration items but rather#persistent information stored in the same place. They are not described here just but #mentionned for information:# call_logs_X : call history items

FAQ

Where can I have a ~/.linphonerc config file ?

You don't need a ~/.linphonerc config file: linphonec automatically creates one during the first startup. There are commands within linphonec to set various parameters. Only a few ones will require to modify manually the config file.

Is there any windows port of linphone ?

Yes, windows XP is totally supported since october 2008.

I have many compilation errors when cross-compiling for ARM-linux !

Cross compilation is not easy: follow the instructions given in the README.arm within linphone's source.

I have audio problems during calls, what can I do ?

Especially on ARM-linux or old versions of linux, the audio devices are often managed with OSS drivers. Linphone, because it uses full-duplex audio and needs low-latency I/O, doesn't work very well with OSS drivers. You should prefer using ALSA drivers and choose the ALSA default device from the Sound Tab of the property box or using the 'soundcard' command of linphonec.

Does linphone work behind firewalls ? What are the ports used ?

Yes it works in most cases. The simplest way to achieve this is to active STUN support from the configuration box. You 'll need to enter the name of a STUN server, for examplestunserver.org. If your firewall or gateway does UDP masquerading, it should work without problem.You may want to restrict the open ports on the firewall: you need at least to preserve the SIP port (udp/5060), the audio rtp port (udp/7078) and the video rtp port (udp/9078). All those ports are configurable from linphone, but keeping 5060 for SIP is highly recommended.Customising audio and video ports is recommended when using several linphone behind a same NAT so that they don't share same port numbers on the NAT. They must be even numbers.

The video quality is awful ! I don't even recognize the person I'm talking with !

this is probably because the video stream is overflowing your internet connection bandwidth, resulting in truncated, dropped or late video packets which makes the image really awful. It is important that you tell linphone about the bandwidth limits (upload and download) of your internet connection. For that go to the 'codec' tab of the property box. Note that a minimum of 128 kbit/s are necessary in upload and download for video to work. The H264 plugin increases the video quality a lot.