Tuning linphone

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 below 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
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 seconds for sending out SIP UDP keepalive to the proxies.
keepalive_period=10
#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
#