Linphone

Overview

Description

Linphone is an open source SIP Phone, available on mobile and desktop environments (iOS, Android, Windows Phone 8, Linux, Windows Desktop, MAC OSX) and on web browsers.

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.

Others OS

Features

Mobile versions

Common features

Main features :

  • Audio call
  • Instant Messaging
  • Pictures and files sharing
  • Account creation assistant
  • Address Book
  • Languages : English, French
  • Call History
  • Display of advanced call statistics
  • Echo Cancellation
  • Quality of Service
  • Secure communications : zRTP (available only under GNU GPL v2 license), TLS, SRTP

Advanced features :

  • Audio codecs : G711, SPEEX, G722, AMR-WB (G722.2), GSM 6.10, AMR-NB, ILBC, SILK, G729
  • Integration with push notification (requires compatible SIP server)
  • Nat friendly: guesses NAT address for SIP messages, uses STUN for RTP streams. Integrated ICE support (RFC5246) to allow peer to peer audio & video connections without media relay server.
  • Low bandwidth mode: make audio calls over EDGE
  • Integrated (in-app) settings

iOS additional features

Additional main features :

  • HD audio and video calls
  • Dedicated tablet user interface
  • Multiple calls support
  • Call Transfer
  • Bluetooth headset support
  • Russian language

Additional advanced features :

  • Audio codecs OPUS
  • Video codecs : H.263, H.264, MPEG-4, VP8
  • Xcode 5 / iOS 7 support

Android additional features

Additional main features :

  • HD audio and video call
  • Dedicated tablet user interface
  • Multiple calls support
  • Call Transfer
  • Bluetooth headset support
  • Multiple accounts support

Additional advanced features :

  • Audio codecs OPUS
  • Video codecs : H.263, H.264, MPEG-4, VP8

Windows Phone 8 versions specificities

Linphone Windows Phone 8 is currently available under proprietary license only. Contact Belledonne Communications for cost, source code (provided after signing an NDA) and other service information.

The video feature is under development and will be available in the next few months.

Desktop versions (Linux, MacOSX and Windows Desktop)

The Gtk2 graphical interface is running on Linux, Windows and MacOSX.

Portability :

  • Linux/x86 and Linux/x86-64
  • Windows XP and Vista
  • MacOS X x86 : audio and video. You can download a standalone bundle from this website or, use macports.
  • Linux/ARM: without graphical interface. Linphonec or liblinphone are good candidates to provide the software stack of an hardware phone or hardware communication system.
  • Linux/Blackfin: The uclinux.org project maintains a port of linphone for blackfin processors, without gui. Performance are impressive. See here for details.

Main features :

  • HD Audio and video call
  • Audio conference
  • Call transfer
  • Call recording
  • Languages : English, French
  • Call History
  • Presence
  • Address Book
  • Echo Cancellation
  • Quality of Service
  • Secure communications (TLS, SRTP, zRTP)

Advanced features :

  • Audio codecs : G711, SPEEX, G722, AMR-WB (G722.2), GSM 6.10, AMR-NB, ILBC, SILK, G729, OPUS
  • Video codecs : H.263, H.264, MPEG-4, VP8
  • Nat friendly: guesses NAT address for SIP messages, uses STUN for RTP streams. Integrated ICE support (RFC5246) to allow peer to peer audio & video connections without media relay server.
  • UPnP (Universal Plug and Play) to allows device-to-device networking of personal computers, networked home appliances and wireless devices
  • Integrated settings
  • Ability to configure multiple proxy accounts with different transports (UDP, TCP, TLS)
  • Supports simultaneous usage of IPv6 and IPv4
  • Permits users to choose between video rendering method on Linux
  • Ability to use keyboard to input DTMF

Liblinphone-level improvements provided by the new "belle-sip" SIP stack:

  • Allows multiple SIP transports simultaneously
  • Supports simultaneous usage of IP Stacks: IPv6 and IPv4 
  • Integrates a fully asynchronous behavior which should decrease lengthy DNS interactions and connections
  • Supports the sip.instance parameter (RFC5626)
  • Supports the alias parameter (RFC5923)
  • Improves management of network disconnections
  • Handles SIP/TLS handled through the lightweighted polarssl library (instead of openssl)
  • Adds improved SIP transaction state machines (RFC6026)
  • Integrates privacy APIs (RFC3323, RFC3325)
  • Supports rich presence in (RFC4480)
  • Improves the handling of Sips scheme in URIs.

Web Plugin

See the dedicated page.

Downloads

License

Linphone is dual licensed. It can be licensed and distributed :

  • under GNU GPLv2 license - for free (open source).
  • under proprietary and commercial license to be used in closed source applications. Contact Belledonne Communications for costs and other service information.

Distros packages : Debian & Ubuntu

Linphone is included in Debian and Ubuntu linux distributions: you can then install it in a few seconds using your favourite package manager or in a console using

sudo apt-get install linphone

See linphone page on debian and ubuntu websites:
http://packages.debian.org/unstable/sound/linphone
http://packages.ubuntu.com/lucid/linphone 

Source code

Clone linphone sources with git :

Project git

linphone, including:

  • oRTP
  • mediastreamer2
  • liblinphone
  • linphonec
  • linphone (gtk)

git clone git://git.linphone.org/linphone.git --recursive

linphone-iphone

  • iPhone app
  • liblinphone
  • msilbc
  • dependencies

git clone git://git.linphone.org/linphone-iphone.git --recursive

linphone-android

  • Android app
  • liblinphone
  • msilbc
  • dependencies

git clone git://git.linphone.org/linphone-android.git --recursive

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.git
Behind a proxy, use http access:
git clone http://git.linphone.org/git/msilbc.git

Codec plugins

We provide codec plugins:

  • msx264: H264 encoder plugin using x264 encoder
  • msilbc: iLBC codec plugin based on c code extracted from IETF RFC page. Source code can be extracted using git repo git://git.linphone.org/libilbc-rfc3951
  • msamr: AMR narrowband plugin based on opencore-amr project. Informative note: AMR usage is governed by a patent license to be acquired from patent holders.
  • mssilk: A SILK plugin based on the Skype implementation.  Informative note: SILK usage is governed by a patent license to be acquired from Skype.
  • msbcg729: A G729 plugin based on our own G729A implementation.  Informative note: G729 usage is governed by a patent license to be acquired from Sipro lab.

Download plugins in source code
Download windows binary plugins

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

Instructions

The instructions are in the README file distributed with the sources.

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
$ linphonec
Ready
Warning: video is disabled in linphonec, use -V or -C or -D to enable.
Place an outgoing call
linphonec> call sip:594305005@someproxy.net
Alternatively, if someproxy.net is your default proxy configuration (entered via 'proxy add' command), you call simply like this
linphonec> call 594305005
Terminate a call
linphonec> terminate
At any time you can list available commands using 'help':
linphonec> help

Commands are:

help Print commands help
call Call a SIP uri
chat Chat with a SIP uri
terminate Terminate the current call
answer Answer a call
autoanswer Show/set auto-answer mode
proxy Manage proxies
soundcard Manage soundcards
webcam Manage webcams
staticpic Manage static pictures when nowebcam
ipv6 Use IPV6
refer Refer the current call to the specified destination.
nat Set nat address
stun Set stun server address
firewall Set firewall policy
call-logs Calls history
friend Manage friends
play play from a wav file
record record to a wav file
quit Exit linphonec
register Register in one line to a proxy
unregister Unregister from default proxy
duration Print duration in seconds of the last call.
status Print various status information
ports Network ports configuration
speak Speak a sentence using espeak TTS engine
codec Audio codec configuration
vcodec Video codec configuration
ec Echo cancellation
mute 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:

#spawn a linphonec daemon:
$ linphonecsh init
#register to a proxy
$ linphonecsh register --host myproxy.net --username bill --password thisisasecret
#dial out
$ linphonecsh dial "sip:alice@myproxy.net"
#terminate the call
$ linphonecsh hangup
#linphonecsh can transmit any command understood by linphonec using the 'generic' keyword
$ linphonecsh generic "proxy list"
#exit the daemon
$ linphonecsh exit

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.

Echo canceller

Linphone uses an echo canceller from libspeexdsp. Filter tail length, echo delay and frame size can be changed.

[sound]
#turn on/off echo cancellation
echocancellation=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

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 level
echolimiter=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 unchanged
el_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_force parameter
#The proportional coefficient controlling the mic attenuation.
#Default value is 10
el_force=10

#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

[sound]
#Automatic gain control (of mic input) - turns on or off:
agc=0

#static software gain (linear scale) to be applied to microphone signal

mic_gain=1.0

#static software gain (log scale) to be applied to signal sent to speaker
playback_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 ringing
remote_ring=/usr/local/share/sounds/linphone/ringback.wav
#wav file to play to advertise incoming calls
local_ring=/usr/loca/share/sounds/linphone/rings/bigben.wav
#turn on/off echo cancellation
echocancellation=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 signal
mic_gain=1.0
#static software gain (log scale) to be applied to signal sent to speaker
playback_gain_db=0.0
##Video settings
[video]
#Size of sent video among these names: QCIF, QVGA, CIF, VGA, SVGA
size=cif
#Whether video is enabled:
enabled=1
#You can refine whether it is enabled for display or capture or both
display=1
capture=1
#Show local preview between calls.
show_local=1
#Show local view during calls, in a corner of the video window
self_view=1
#Webcam name for capture
device=V4L2: /dev/video0
##Network settings
[net]
#Estimated download bandwidth in kbit/s
download_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/s
upload_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=2
stun_server=stun.ekiga.net
#Firewall address to use when in firewall_policy=1
nat_address=80.112.33.11
##SIP settings
[sip]
#SIP port used
sip_port=5060
#Discover automatically local IP address
guess_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 timeout
inc_timeout=15
#Use SIP INFO to send DTMFs (digits)
use_info=0
#Use RFC2833 (out of band DTMFs) to send digits
use_rfc2833=0
#Use IPv6. caution: it is exclusive with IPv4.
use_ipv6=0
#Send registers only when network is up
register_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
## RTP settings
[rtp]
#Audio RTP (UDP) port
audio_rtp_port=7078
#Video RTP (UDP) port
video_rtp_port=9078
#Nominal audio jitter buffer size in milliseconds
audio_jitt_comp=60
#Nominal video jitter buffer size in milliseconds
video_jitt_comp=60
#RTP timeout in seconds: when no RTP or RTCP
# packets are received for this period, the running call is
# automatically closed.
nortp_timeout=30
## 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 enabled
enabled=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 enabled
enabled=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 proxy
reg_proxy=sip:example.net
#SIP identity for which you are known on this proxy:
reg_identity=
#Expiration period of the registration in seconds
reg_expires=3600
#Whether to send a register or not
reg_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 00
dial_escape_plus=0
#Phone number prefix to be applied to entered destinations.
#Example: prefix=+33
prefix=
## 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 username
username=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 realm
passwd=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 buddy
url=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 person
pol=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.