Linphone

Build

The generic steps to build the SDK are:

Create and go inside a directory where the SDK will be built:
Execute CMake to configure the project:
Build the SDK:

or
(which is faster).

The options below define the target of the compilation, and hence are required most of the time:

: The platform for which you want to build the Linphone SDK. It must be one of: , , Raspberry or Desktop (default value).
: By default it is set to to build in release mode keeping the debug information. You might want to set it to to ease the debugging. On Android, use to make a build linking with the Android Adress Sanitizer (https://github.com/google/sanitizers/wiki/AddressSanitizerOnAndroid).

These generic steps work for all platforms, but a few specifics behaviors are good to know and are described
in the next subsections.

iOS

Requirement: Xcode 11 or 10.

Cmake has limited swift support: only Ninja and Xcode generators can handle swift.
Until cmake has full swift support, you need to specify configuration step by specifying one of the two backends:

If using the Xcode generator, the build type must be specified for compilation step with :
, where is one of , , or .
If nothing is specified, the SDK will be built in Debug mode.

Please note that the Xcode backend is very slow: about one hour of build time, compared to approximately 15 mn for Ninja.

Windows

works on Windows as for all platforms.
However it may be convenient to build from Visual Studio, which you can do:

open with Visual Studio
make sure that RelWithDebInfo mode is selected unless you specified -DCMAKE_BUILD_TYPE=Debug to cmake (see customization options below).
use to build.

Implemented standards

Microsip online help

REGISTRATION, CALLS, CORE FUNCTIONS

Session Initiation Protocol, RFC 3261
- 8. General User Agent behaviour
- 9. Cancelling a request
- 10. Registrations
- 12. Dialogs
- 13. Initiating a session
- 14. Modifying an existing session
- 15. Terminating a session
- 17. Transactions
- 18. Transports
- 22.4 The Digest Authentication Scheme
Session Initiation Protocol (SIP): Locating SIP Servers, RFC 3263
Session Description Protocol, RFC 4566
An Offer/Answer Model with the Session Description Protocol (SDP), RFC 3264
An Extension to the Session Initiation Protocol (SIP), RFC 3581 (use of rport parameter)
Session Initiation Protocol (SIP) INFO Method and Package Framework, RFC 6086
4. The INFO Method
The Session Initiation Protocol (SIP) Refer Method, RFC 3515
2. The REFER Method
Session Description Protocol (SDP) Security Descriptions for Media Streams, RFC 4568
Negotiating Media Multiplexing Using the Session Description Protocol (SDP), draft-ietf-mmusic-sdp-bundle-negotiation-54
Managing Client-Initiated Connections in the Session Initiation Protocol (+sip.instance parameter), RFC 5626
Connection reuse in the Session Initiation Protocol (alias parameter), RFC 5923
Correct Transaction Handling for 2xx Response to Session Initiation Protocol (SIP) INVITE Requests, RFC 6026
A privacy mechanism for the Session Initiation Protocol, RFC 3323
Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks, RFC 3325
Interactive Connectivity Establishment (ICE), RFC 5245
Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN), RFC 5766
Session Traversal Utilities for NAT (STUN), RFC 5389
Traversal Using Relays around NAT (TURN) Resolution Mechanism, RFC 5928
Re-INVITE and Target-Refresh Request Handling, RFC 6141, chpt. 5 only
Reliability of Provisional Responses in the Session Initiation Protocol (SIP), RFC 3262
RTP Header Extension for the RTP Control Protocol (RTCP) Source Description Items, RFC 7941
A General Mechanism for RTP Header Extensions, RFC 8285

PRESENCE

A Presence Event Package for the Session Initiation Protocol (SIP), RFC 3856
Session Initiation Protocol (SIP) Extension for Event State Publication, RFC 3903 (Creation of PUBLISH requests)
A Data Model for Presence, RFC 4479
RPID: Rich Presence Extensions to the Presence Information Data Format (PIDF), RFC 4480
Subscriptions to Request-Contained Resource Lists in the Session Initiation Protocol (SIP), RFC 5367
Session Initiation Protocol (SIP) — Specific Event Notification, RFC 6665
Message Body Handling in the Session Initiation Protocol, RFC 5621
SIP body compression, RFC 1951

ONE-TO-ONE & GROUP INSTANT MESSAGING

Session Initiation Protocol, RFC 3261
The Session Initiation Protocol (SIP) Refer Method, RFC 3515
2. The REFER Method
Session Initiation Protocol (SIP) Extension for Instant Messaging, RFC 3428 (only text/plain messages)
SIP Call Control — Conferencing for User Agents, RFC 4579
Conference Establishment Using Request-Contained Lists in SIP, RFC 5366
SIP Event Package for Conference State, RFC 4575
Obtaining and Using Globally Routable User Agent URIs (GRUUs) in SIP, RFC 5627
Subscriptions to Request-Contained Resource Lists in the Session Initiation Protocol (SIP), RFC 5367
Session Initiation Protocol (SIP) — Specific Event Notification, RFC 6665
Common Presence and Instant Messaging (CPIM): Message Format, RFC 3862
Indication of message composition in instant messaging, RFC 3994
Instant Message Disposition Notification, RFC 5438
File transfer also possible via HTTP POST/GET — RCS vnd.gsma.rcs-ft-http+xml
SIP body compression, RFC 1951
Message Body Handling in the Session Initiation Protocol, RFC 5621

VCARD

§ LinphoneAuthInfo

typedef struct _LinphoneAuthInfo

Bria

Object holding authentication information.

Note: The object’s fields should not be accessed directly. Prefer using the accessor methods.

In most case, authentication information consists of a username and password. Sometimes, a userid is required by proxy, and realm can be useful to discriminate different SIP domains.

Once created and filled, a LinphoneAuthInfo must be added to the LinphoneCore in order to become known and used automatically when needed. Use for that purpose.

The LinphoneCore object can take the initiative to request authentication information when needed to the application through the auth_info_requested callback of the LinphoneCoreVTable structure.

The application can respond to this information request later using . This will unblock all pending authentication transactions and retry them with authentication headers.

§ linphone_auth_info_new()

* linphone_auth_info_new	(	const char *	username,
		const char *	userid,
		const char *	passwd,
		const char *	ha1,
		const char *	realm,
		const char *	domain
	)

Zoiper sdk fact sheet

Creates a object with supplied information. The object can be created empty, that is with all arguments set to NULL. Username, userid, password, realm and domain can be set later using specific methods. At the end, username and passwd (or ha1) are required.

Parameters

username	The username that needs to be authenticated
userid	The userid used for authenticating (use NULL if you don’t know what it is)
passwd	The password in clear text
ha1	The ha1-encrypted password if password is not given in clear text.
realm	The authentication domain (which can be larger than the sip domain. Unfortunately many SIP servers don’t use this parameter.
domain	The SIP domain for which this authentication information is valid, if it has to be restricted for a single SIP domain.

Returns: A object. linphone_auth_info_destroy() must be used to destroy it when no longer needed. The LinphoneCore makes a copy of LinphoneAuthInfo passed through .

Instant Messaging features

One-to-one and group text instant messaging. Liblinphone’s group chat implementation is based on the SIP protocol, and uses signaling flows described in RCS specifications. We aim to converge to RCS compliance in future versions.
End-to-end encryption with the implementation of the Double Ratchet Algorithm and Perfect Forward Secrecy
«Is typing» and delivery notifications (undelivered, delivered, read, error)
File sharing (images, videos, documents, vCards etc.)

Liblinphone leverages the Mediastreamer2 engine for rendering audio and video streams, and thus can take advantage of all the features implemented in Mediastreamer2.
For more information, see the complete list of media features in the Mediastreamer2 section.

§ linphone_chat_room_create_message_2()

* linphone_chat_room_create_message_2	(	*	cr,
		const char *	message,
		const char *	external_body_url,
			state,
		time_t	time,
		bool_t	is_read,
		bool_t	is_incoming
	)

Create a message attached to a dedicated chat room;

Parameters

cr	the chat room.
message	text message, NULL if absent.
external_body_url	the URL given in external body or NULL.
state	the LinphoneChatMessage.State of the message.
time	the time_t at which the message has been received/sent.
is_read	TRUE if the message should be flagged as read, FALSE otherwise.
is_incoming	TRUE if the message has been received, FALSE otherwise.

Returns: a new

Customizing the build

The SDK compilation can be customized by passing options to CMake when configuring the project. If you know the options you want to use, just pass them to CMake.

Otherwise, you can use the or commands to configure all the available options interactively.

The following options control the cpu architectures built for a target platform:

: A comma-separated list of the architectures for which you want to build the Android Linphone SDK for.
: Same as but for an iOS build.
: The base of the URL that will be used to download the zip file of the SDK.
: Same as but for an UWP build.

These ON/OFF options control the enablement of important features of the SDK, which have an effect on the size of produced size object code:

: enablement of video call features.
: enablement of group chat and secure IM features
: enablement of ZRTP ciphering
: enablement of database storage for IM.
: enablement of Vcard features.
: enablement of Matroska video file reader/writer.

§ linphone_core_create_auth_info()

* linphone_core_create_auth_info	(	*	lc,
		const char *	username,
		const char *	userid,
		const char *	passwd,
		const char *	ha1,
		const char *	realm,
		const char *	domain
	)

Create an authentication information with default values from Linphone core.

Parameters

	lc	object
	username	String containing the username part of the authentication credentials
	userid	String containing the username to use to calculate the authentication digest (optional)
	passwd	String containing the password of the authentication credentials (optional, either passwd or ha1 must be set)
	ha1	String containing a ha1 hash of the password (optional, either passwd or ha1 must be set)
	realm	String used to discriminate different SIP authentication domains (optional)
	domain	String containing the SIP domain for which this authentication information is valid, if it has to be restricted for a single SIP domain.

Returns: with default values set

Build dependencies

Common to all target platforms

The following tools must be installed on the build machine:

cmake >= 3.6
python = 2.7 (python 3.7 if C# wrapper generation is disabled)
pip
yasm
nasm
doxygen
Pystache (use )
six (use )

Windows

SDK compilation is supported on Visual Studio 15 2017.
Setting the build environment on Windows is a bit tricky.
In addition to the common components listed above, these components must be installed:

MinGW (select all installer options except Ada and Fortran)
Yasm:
- download yasm-1.3.0-win32.exe
- copy it to a directory of your user directory,
- rename yasm-1.3.0-win32.exe as yasm.exe

Visual Studio must also be properly configured with addons. Under «Tools»->»Obtain tools and features», make sure that the following components are installed:

Tasks: Select Windows Universal Platform development, Desktop C++ Development, .NET Development
Under «Installation details». Go to «Desktop C++ Development» and add «SDK Windows 8.1 and SDK UCRT»
Individual component: Windows 8.1 SDK

Finally add your user directory and to the PATH environement variable from windows advanced settings.

To run the liblinphone test suite on android

Simply run . This will be build everything, generate an apk, and install it on the connected device if any.

TROUBLESHOOTING

If you encounter the following issue:

It’s because you have installed the android-21 platform (which is chosen automatically because it’s the most recent) and you deployed the apk on a android < 5 device.

To fix this, in the Makefile, force ANDROID_MOST_RECENT_TARGET=android-19.

If you built the app using eclipse, ensure you ran at least once the make command (see above steps 0 to 3) ! Else you’ll have this exceptions:

BUILD OPTIONS

The build options are to be passed to the prepare.py script. For example to enable the x264 encoder give the «-DENABLE_X264=YES» to prepare.py.

The available options can be listed with the

Media features

Audio codecs: opus, speex, g711, g729, gsm, iLBC, AMR, AMR-WB, g722, SILK, iSAC, BV16, Codec2
Video codecs: VP8, MPEG4, and hardware accelerated H.264 and H.265 codecs for macOS / iOS (VideoToolbox) and Android (MediaCodec) with resolutions up to 1080p.
Audio conferencing
Call recording (audio and video)
Innovative RTP jitter buffer algorithm, which quickly adapts to network conditions with a lot of jitter and improves control of the audio latency
Adaptive bit rate control algorithm: congestion control and estimation of available bandwidth, in order to optimise the quality of audio and video
ICE (RFC 5245), STUN and TURN (RFC 5766) for optimised NAT traversal allowing peer-to-peer audio and video connections whenever possible
SRTP, zRTP and SRTP-DTLS voice and video encryption

How to be a beta tester ?

Enter the Beta :

Download TestFlight from the App Store and log in it with your apple-id
-Tap the public link on your iOS device. The public link : https://testflight.apple.com/join/LUlmZWjH
-Touch View in TestFlight or Start Testing. You can also touch Accept, Install, or Update for Linphone app.
-And voilà ! You can update your beta version with the same public link when a new one is available

Send a crash report :

It is done automatically by TestFlight

Report a bug :

Open Linphone
Go to Settings —> Advanced —> Send logs
An email to linphone-iphone@belledonne-communications.com is created with your logs attached
Fill in the bug description with :
- What you were doing
- What happened
- What you were expecting
- Approximately when the bug happened
Change the object to
Send the mail

XML formatted configuration file

An XML converted configuration file looks like this:

If you want to apply your changes only once (eg. not at each start, you have to enable the transient_provisioning parameter):

The mapping between INI and XML representation is quite obvious.A tool is integrated into the Linphone desktop version in order to convert from INI-style to XML.Here’s typical usage of:

./tools/lpc2xml_test convert /.linphonerc /tmp/linphonerc.xml

: By default, lpc2xml will produce an XML that will not overwrite existing keys.If you want to overwrite the existing configuration, you must append the overwrite=»true» attribute for each key that you want to override, i.e.:

Description

Liblinphone is a high-level library integrating all SIP calls and instant messaging features into a single easy-to-use API.

Two things are generally involved in telecommunications: media (transport of voice or video, encoding and decoding etc.), and signaling (routing calls, ringing, accepting a call etc.).

Liblinphone combines these two aspects together to do most of these things automatically. This makes it easier for the programmer to implement video calls and instant messaging in any application, without being an expert in VoIP and telecommunications. Liblinphone is an open source library that is based on Mediastreamer2 for voice/video streaming and belle-sip for SIP signaling.

The Liblinphone stack is suitable for building a VoLTE-compatible client, thanks to its interoperability with IMS networks and its available extension API.

The Mediastreamer2 plugin API can be used to incorporate the EVS codec
The low-level RTP transport API is suitable for interfacing with an API stack implementing RoHC (Robust Header Compression, RFC 3095)

Mobile-specific features (iOS/Android)

Multi-participant Instant Messaging (group chat)
End-to-end encryption for both 1-to-1 and group instant messages (requires LIME library)
Smart contact list (shows people using the service) using list subscription to a presence server
Provisioning via QR Code
Support for bluetooth headset
Dedicated tablet user interface
Blind accessibility
Replay of recorded calls from the «Recordings» menu
Configurable setting to automatically / manually download attachments

Linphone is available on the following mobile platforms:

Apple iOS 9 to 13 (ARM v7, ARM 64)
Google Android 5.0 to 10 (ARM v7, ARM 64, x86, x86-64)

iOS ADDITIONAL FEATURES

AAC-ELD support

ANDROID ADDITIONAL FEATURES

Video overlay

To build liblinphone for Android, you must:

Download the Android sdk (API 23 at least) with platform-tools and tools updated to latest revision, then add both ‘tools’ and ‘platform-tools’ folders in your path.
Download the Android ndk (version r11c or 12b) from google and add it to your path (no symlink !!!).
Install yasm, nasm, ant, python, intltoolize, cmake and vim-common.

On 64 bits linux systems you’ll need the ia32-libs package.
With the latest Debian (multiarch), you need this:

Run in the top level directory. This will configure the build and generate a Makefile in the top level directory. Some options can be passed to choose what you want to include in the build and the platforms for which you want to build. Use to see what these options are.
Run the Makefile script in the top level directory, .
(optional) To install the generated apk into a plugged device, run .
(optional) To generate a liblinphone SDK zip containing a full jar and native libraries, run
(optional) To generate a libmediastreamer2 SDK zip containing a full jar and native libraries, run
(optional) To generate a signed apk to publish on the Google Play, run . Make sure you filled the ant.properties values for version.name, key.store and key.alias in order to correctly sign the generated apk. You also may want to create a file name ant_password.properties with the following:

key.store.password=
key.alias.password=

If you don’t, the passwords will be asked at the signing phase.

(optional) Once you compiled the libraries succesfully with ‘make’, you can reduce the compilation time using ‘make quick’: it will only generate a new APK from java files.

Summary¶

Properties

	Refine bandwidth settings for this call by setting a bandwidth limit for audio streams.
	Get the audio stream direction.
	Tell whether audio is enabled or not.
	Use to get multicast state of audio stream.
	Gets a list of set if exists.
	Indicate whether sending of early media was enabled.
	Tell whether the call is part of the locally managed conference.
	Tell whether the call has been configured in low bandwidth mode or not.
	Get the kind of media encryption selected for the call.
	Get requested level of privacy for the call.
	Use to get real time text following rfc4103.
	Use to get keep alive interval of real time text following rfc4103.
	Get the framerate of the video that is received.
	Get the definition of the received video.
	Get the path for the audio recording of the call.
	Indicates whether RTP bundle mode (also known as Media Multiplexing) is enabled.
	Get the RTP profile being used.
	Get the framerate of the video that is sent.
	Get the definition of the sent video.
	Get the session name of the media session (ie in SDP).
	Get the audio payload type that has been selected by a call.
	Get the text payload type that has been selected by a call.
	Get the video payload type that has been selected by a call.
	Get the video stream direction.
	Tell whether video is enabled or not.
	Use to get multicast state of video stream.

Common Features (Mobile and Desktop)

OVERALL FEATURES

HD audio and video calls
Multiple call management (pause and resume)
Call transfer
Audio conferencing (merge calls into a conference call)
Call recording and replay (audio only)
Instant Messaging
Message delivery status (IMDN)
Picture and file sharing
Message forwarding (Android only)
Chat access during calls
Contact list
«Invite your friends» feature
Call history
Display of advanced call statistics
Echo cancellation
Call quality indicator
Secure user authentication: md5 / SHA256 digest, TLS client certificates
SRTP, zRTP and SRTP-DTLS voice and video encryption
Supported languages: English, French
Account creation assistant
Remote provisioning

ADVANCED FEATURES

Audio codecs: opus, speex, g711, g729, gsm, iLBC, AMR, AMR-WB, g722, SILK, iSAC, BV16, Codec2
Video codecs: VP8, H.264 and H.265 with resolutions up to 1080P, MPEG4
Hardware accelerated H.264 and H.265 codec for Mac OSX / iOS (VideoToolbox) and Android (MediaCodec)
Innovative RTP jitter buffer algorithm, which quickly adapts to network conditions with a lot of jitter and improves control of the audio latency
Adaptive bit rate control algorithm: congestion control and estimation of available bandwidth, in order to optimise the quality of audio and video
Integration with push notification (requires compatible SIP server;linphone.org SIP service is push enabled)
ICE (RFC 5245), STUN and TURN (RFC 5766) for optimised NAT traversal, allowing for peer-to-peer audio and video connections whenever possible
Low bandwidth mode for audio calls over 2G networks
Call handover accross a change of network access type (e.g. start a call in wifi and continue in 3G)
Ability to configure multiple proxy accounts with different transports protocols (UDP, TCP, TLS)
IPv6 (dual-stack and v6-only support)
DTMF (telephone tone) support using SIP INFO or RFC 4733

For more information, consult the complete list of implemented standards in the Liblinphone section.

Google

To enable google push in Linphone, remove ‘google-service.json’ file if it exist, add your key at ‘push_sender_id’ and add ‘google’ at ‘push_type’ in ‘res/values/non_localizable_custom.xml’
Be sure to have every permissions and services for GCM in your ‘AndroidManifest.xml’

TROUBLESHOOTING

If you encounter the following issue:

It’s because you have installed the android-21 platform (which is chosen automatically because it’s the most recent) and you deployed the apk on a android < 5 device.

To fix this, in the Makefile, force ANDROID_MOST_RECENT_TARGET=android-19.

If you built the app using eclipse, ensure you ran at least once the make command (see above steps 0 to 3) ! Else you’ll have this exceptions:

BUILD OPTIONS

The build options are to be passed to the prepare.py script. For example to enable the x264 encoder give the «-DENABLE_X264=YES» to prepare.py.

The available options can be listed with the

CONTRIBUTIONS

In order to submit a patch for inclusion in linphone’s source code:

First make sure your patch applies to latest git sources before submitting: patches made to old versions can’t be merged.

Importing liblinphone SDK

Two options are available. The first one is to configure our maven repository in your build.gradle file and add our SDK dependency. The second one is to manually download and install our SDK.

Use our Maven repository

Edit your top level gradle build file and edit the allprojects’ repositories list to add our own:

maven { url «https://linphone.org/maven_repository/»}

Then in your app’s gradle build file add the either one of the following to your dependencies list:

debugImplementation «org.linphone:linphone-sdk-android-debug:4.3+»releaseImplementation «org.linphone:linphone-sdk-android:4.3+»

Before 4.0.1 there is only a release implementation available !

Changes starting with 4.1:

The artifact id is now linphone-android-sdk instead of liblinphone-sdk.
A no-video build is available with the group id org.linphone.no-video instead of org.linphone.
The javadoc is also available with the release AAR

Here’s a sample on how to the latest snapshot:

debugImplementation «org.linphone:linphone-sdk-android-debug:4.3+»releaseImplementation «org.linphone:linphone-sdk-android:4.3+»

For the no-video builds, use

debugImplementation «org.linphone.no-video:linphone-sdk-android-debug:4.3+»releaseImplementation «org.linphone.no-video:linphone-sdk-android:4.3+»

If you want the smallest AAR available (with most of the features being disabled to gain some space such as video, advanced IM, sqlite, vCard, MKV, plugins, etc…):

debugImplementation «org.linphone.minimal:linphone-sdk-android-debug:4.3+»releaseImplementation «org.linphone.minimal:linphone-sdk-android:4.3+»

Finally, for those who still uses the old Java wrapper but still want to be able to update the library, we have created a legacy package

debugImplementation «org.linphone.legacy:linphone-sdk-android-debug:4.3+»releaseImplementation «org.linphone.legacy:linphone-sdk-android:4.3+»

Keep in mind that the debug AAR is a lot bigger than the release one, thus the APK installation will take some time.So for day to day development, you can use the release AAR to have faster builds.

Download our SDK

You can download the AAR directly from the maven repository.

To configure your project, put the aar in the libs/ directory should be enough.

In your build.gradle add in repositories:

repositories { … flatDir { dirs ‘libs’ }}

If for some reason it’s not (for example if you decided to put the aar in another folder), just add the folder to flatDir.

And in dependencies:

repositories{…//compile(name:’liblinphone-sdk-release’,ext:’aar’)Thiswastheoldwayandstillworksbutyou’ll have a warning implementation ‘org.linphone.core:liblinphone-sdk-release@aar’}

And now you have liblinphone sdk integrated in your project.

You can try your setup by trying to start a sample Core:

Factory.instance().setDebugMode(true, «Linphone»);// You must provide the Android app context as createCore last param !Core core = Factory.instance().createCore(null, null, this.getApplicationContext());core.start();

You MUST provide the Android app context as createCore last param !