Package org.linphone.core

Liblinphone is a high level library for bringing SIP video call functionnality into an application.

See: Description

Package org.linphone.core Description

Liblinphone is a high level library for bringing SIP video call functionnality into an application. It aims at making easy the integration of the SIP video calls into any applications. All variants of linphone are directly based on it:
  • linphone (GUI interface)
  • linphonec (console interface)
    Liblinphone is GPL (see COPYING file). Please understand the licencing details before using it!
    For any use of this library beyond the rights granted to you by the GPL license, please contact Belledonne Communications (contact@belledonne-communications.com)

    Package Specification

    LibLinphone package is organized in submodules.

    Related Documentation

    For overviews, tutorials, examples, guides, and tool documentation, please see:

    Managing proxies

    User registration is controled by LinphoneProxyConfig settings.
    Each LinphoneProxyConfig object can be configured with registration informations like proxy address , user id, and so on.
    A created proxy config using org.linphone.core.LinphoneCoreFactory#createProxyConfig , once configured, must be added to LinphoneCore using function LinphoneCore.addProxyConfig(org.linphone.core.LinphoneProxyConfig).
    It is recommended to set a default proxy config using function LinphoneCore.setDefaultProxyConfig(org.linphone.core.LinphoneProxyConfig). Once done, if a proxy config has been configured with attribute enable register , next call to LinphoneCore.iterate() triggers a SIP register.
    Registration status is reported by registration listener.

    This pseudo code demonstrates basic registration operations: 
    
        
        LinphoneProxyConfig proxy_cfg;
        /*create proxy config*/
        proxy_cfg = LinphoneCoreFactory.instance().createProxyConfig();
        /*parse identity*/
        LinphoneAddress from = LinphoneCoreFactory.instance().createAddress("sip:toto@sip.titi.com");
        LinphoneAuthInfo info;
        if (password!=NULL){
                info=LinphoneCoreFactory.instance().createAuthInfo(from.getUsername(),null,"secret",null,null); /*create authentication structure from identity*/
                lc.addAuthInfo(info); /*add authentication info to LinphoneCore*/
        }       
        // configure proxy entries
        proxy_cfg.setIdenty(identity); /*set identity with user name and domain*/
        String server_addr = from.getDomain(); /*extract domain address from identity*/
        proxy_cfg.setProxy(server_addr); /* we assume domain = proxy server address*/
        proxy_cfg.enableRegister(true); /*activate registration for this proxy config*/
        
        lc.addProxyConfig(proxy_cfg); /*add proxy config to linphone core*/
        lc.setDefaultProxyconfig(proxy_cfg); /*set to default proxy*/

    Registration state listener : 
    
 void registrationState(LinphoneCore lc, LinphoneProxyConfig cfg, LinphoneCore.RegistrationState cstate, String message){
                System.out.println(New registration state ["+cstate+"] for user id ["+cfg.getUserName()+"] at proxy ["+cfg.getProxy()+"]";
}

    Authentication:
    Most of the time, registration requires authentication to succed. LinphoneAuthInfo info must be either added to LinphoneCore using method LinphoneCore.addAuthInfo(org.linphone.core.LinphoneAuthInfo) before LinphoneProxyConfig is added to Linphone core, or on demand from listener org.linphone.core.LinphoneCoreListener#authInfoRequested(LinphoneCore, String, String) .

    Unregistration:
    Unregistration or any changes to LinphoneProxyConfig must be first started by a call to function LinphoneProxyConfig.edit() and validated by function LinphoneProxyConfig.done()
    This pseudo code shows how to unregister a user associated to aLinphoneProxyConfig 
    
        LinphoneProxyConfig proxy_cfg;
        lc.setDefaultProxyConfig(proxy_cfg); /* get default proxy config*/
        proxy_cfg.edit(); /*start editing proxy configuration*/
        proxy_cfg.enableRegister(false); /*de-activate registration for this proxy config*/
        proxy_cfg.done(); /*initiate REGISTER with expire = 0*/


    Managing Buddies and buddy list and presence


    Buddies and buddy list
    Each buddy is represented by a LinphoneFriend object created by function LinphoneCoreFactory.createLinphoneFriend(). Buddy configuration parameters like sip uri or status publication are configurable for each buddy.
    Here under a typical buddy creation: 
    
        LinphoneFriend my_friend=LinphoneFactory.instance().createFriend("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
        my_friend.enableSubscribes(true); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
        my_friend.setIncSubscribePolicy(LinphoneFriend.SubscribePolicy.Accept); /* accept Incoming subscription request for this friend*/
    friends status changes are reported by LinphoneCoreListener.notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf) . 
    
 void notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf){
        LinphoneAddress friend_address = lf.getAddress();
        System.out.println("New state ["+lf.getStatus()+"] for user id ["+friend_address+"] ");
}

    Once created a buddy can be added to the buddy list using function LinphoneCore.addFriend(LinphoneFriend lf) . Added friends will be notified about local status changes
    Any subsequente modifications to LinphoneFriend must be first started by a call to function to LinphoneFriend.edit() and validated by function LinphoneFriend.done() 
    
        my_friend.edit(); /* start editing friend */
        my_friend.enableSubscribes(true); /*disable subscription for this friend*/
        my_friend.done(); /*commit changes triggering an UNSUBSCRIBE message*/
    Publishing presence status
    Local presence status can be changed using function LinphoneCore.setPresenceInfo(int, java.lang.String, org.linphone.core.OnlineStatus).New status is propagated to all friends previously added to LinphoneCore.

    Handling incoming subscription request
    New incoming subscription requests are process according tothe incoming subscription policy state for subscription initiated by members of the buddy list.
    For incoming request coming from an unknown buddy, the call back LinphoneCoreListener.newSubscriptionRequest(LinphoneCore lc, LinphoneFriend lf, String url)

    Chat room and Messaging

    Exchanging text messages
    Messages are sent using LinphoneChatRoom object. First step is to create a chat room from a peer sip uri. 
    
        LinphoneChatRoom chat_room = lc.createChatRoom("sip:joe@sip.linphone.org");

    Once created, messages are sent using function LinphoneChatRoom.sendMessage(java.lang.String) . 
    
        chat_room.sendMessage("Hello world"); /*sending message*/

    Incoming message are received from a listener 
    
        void textReceived(LinphoneCore lc, LinphoneChatRoom cr,LinphoneAddress from,String message) {
                System.out.println("Message ["+message+"] received from ["+from+"] ");
        }

    Sound and echo cancellation settings

    Sound levels
    It is possible to tune the microphone input gain and speaker/receiver output gain by setting parameters into the linphonerc factory config file loaded when instanciating the LinphoneCore. These gains are liblinphone's internal software gains and are unrelated to volume levels managed by the operating system. For example: 
    
[sound]
#set the speaker or receiver playback gain in dbm0 (0 db = no change). 
playback_gain_db=-3
#set the microphone gain in linear scale:
mic_gain=0.1

    Echo cancellation
    On Android devices, there are two kind of situations regarding echo cancellation:
    • The new (after 2011) high end devices, on which manufacturers often include a hardware echo cancellation. If available, liblinphone will make use of it and no software correction is required. Source file linphone-android/submodules/linphone/mediastreamer2/java/src/org/linphone/mediastream/video/capture/hwconf/Hacks.java contains a method hasBuiltInEchoCanceller() that returns true if an hardware echo canceller is available, based on device model identifier. The current list is incomplete.
    • The other devices, for which it is recommended to enable the software echo canceller of liblinphone.

    Echo calibration tool
    The echo calibration procedure is a five second audio test which consists in playing small beeps to the receiver while the microphone input is recorded. If the device is subject to echo (or doesn't have hardware echo cancellation), then beeps recorded by the microphone will be detected and a measurement of echo delay can be computed. Echo calibration procedure can be started by calling LinphoneCore.startEchoCalibration. The measurement of the echo delay is important to save CPU computations by restricting the temporal area where the software echo canceller has to perform.

    Echo limiter
    The echo limiter is a liblinphone algorithm to clear out echo with a brute force method. It consists in cutting down the microphone signal when active signal is played by the speaker/receiver, to prevent voice to feed back into the microphone. This algorithm has disadvantages compared to the hardware or software echo cancellers because the remote user will be not hear any background noise when speaking, which is confusing. As a result the echo limiter method shall be used only under situation where echo canceller can't perform, that is loud signals with heavy saturations, which usually happens when using the device in speaker mode. Echo limiter can be enabled or disabled during a call with LinphoneCall.enableEchoLimiter().

    Recommandations to applications for optimal audio performance

    In order to benefit from the best echo cancellation solution, we recommend applications to run the following procedure, when they are run for the first time:
    • Use the Hacks.hasBuiltInEchoCanceller() method to first check if the device has hardware echo cancellation. If yes, then echo canceller must be turned off.
    • If hasBuiltInEchoCanceller() returned false, then it is recommended to run the echo calibration procedure. This procedure can produce the following results:
      • success with no echo detected: it means that the device has an hardware echo canceller but is not (yet) referenced in our list of devices having hardware echo cancellation. Echo cancellation should be disabled with LinphoneCore.enableEchoCancellation(false)
      • success with an estimated echo delay: the echo canceller should be enabled.
      • failure: it means that some echo has been detected but the delay could not be estimated. In this case it is recommended to activate the echo canceller. A typical for android minimum delay of 250 ms will be used as default.
    During calls, the echo limiter should be disabled while using the receiver, but enabled while using the hands-free speaker. It is also recommended to disable echo canceller while using the echo limiter, because the first one would be useless. Therefore you should have the following situations:
    • While using the receiver
      • Echo canceller enabled, unless the device has hardware echo cancellation
      • Echo limiter disabled
    • While using the hands-free speaker
      • Echo canceller disabled
      • Echo limiter enabled, unless the device has hardware echo cancellation.
    Controlling echo limiter during a call has to be done with LinphoneCall.enableEchoLimiter(). Controlling echo canceller during a call has to be done with LinphoneCall.enableEchoCancellation().

    Echo limiter settings
    Echo limiter requires settings to be defined in linphonerc factory config file for correction operation. Typical settings are: 
    
[sound]
el_type=mic
#speaker energy threshold (linear scale) above which echo limiter decreases mic gain.
el_thres=0.03
#attenuation applied to mic gain (linear scale)
el_force=100000
#minimum time in milliseconds during which attenuation is applied
el_sustain=600
#double talk detection: threshold of ratio mic-energy/speaker-energy above which mic input is sent anyway.
el_transmit_thres=1.7
#noise gate floorgain (gain applied when no voice is detected).
ng_floorgain=0.01
    Up to date settings must be found from linphone-android/res/raw/linphonerc file.