Skip to Content

Linphone-sdk developer guide

Last modified by Simon Morlat on 2025/12/24 15:44

The linphone-sdk project provides Liblinphone, a high-level SIP library integrating all calling and instant messaging features into an unified easy-to-use API.
It is the cross-platform VoIP library on which the Linphone application is based, and that anyone can use to add audio and video calls or instant messaging capabilities to an application.

Liblinphone offers a consistent API for C, C#, C++, java and swift.

The below example shows out to make a simple SIP outgoing call:

Swift

let callee : Address = try! Factory.Instance.createAddress(addr: "sip:janedoe@sip.exemple.org");
let callParams : CallParams = try! core.createCallParams(call: nil)
let call : Call? = core.inviteAddressWithParams(addr: callee, params: callParams)
let callStateDelegate = CallDelegateStub(onStateChanged: { (thisCall: Call, state: Call.State, message : String) in
        if (state == Call.State.Connected) { NSLog("Call is connected")    }
        else { NSLog("Call is \(state)") }
})
call?.addDelegate(delegate: callStateDelegate)

C#

Address callee = Factory.Instance.CreateAddress("sip:janedoe@sip.exemple.org");
CallParams callParams = Core.CreateCallParams(null);
Call call = Core.InviteAddressWithParams(callee, callParams);
call.Listener.OnStateChanged += (Call delegateCall, CallState state, string message) =>
    {
        switch (state)
        {
            case CallState.Connected:
                loggingService.Message("Call is connected");
                break;
            default:
                loggingService.Message("Call is " + state.ToString());
                break;
        };
    };

Kotlin

val callee = Factory.instance().createAddress("sip:janedoe@sip.example.org")
val params = core.createCallParams(null)
val call = core.inviteAddressWithParams(callee, params)
call?.addListener(object: CallListenerStub() {
    override fun onStateChanged(call: Call, state: Call.State, message: String) {
        when (state) {
            Call.State.Connected -> Log.i("Call is connected")
            else -> Log.i("Call is $state")
        }
    }
})

The application integration has been made easy thanks to Swift Package Manager (iOS/macOS) and Maven (Android).

General description is available from linphone web site.

Table of contents

Portability

The linphone-sdk project is cross-platform and can be used across multiple programming languages.

Operating SystemMinimum OS version requiredSupported processor architecturesAvailable languages 
Android6arm64Java/Kotlin, C# (MaUI package) 
iOS15arm64, x86_64C, C++, Swift, C# (MaUI package) 
GNU/LinuxDebian 9, Rocky Linux 8, Yoctox86, x86_64, arm64, armv7C, C++, C#, Java/Kotlin, Python 
Windows10x86_64, x86C, C++, C#, Java/Kotlin 
Mac OS13arm64, x86_64C, C++, Swift 

Tutorials

Tutorials are available on our dedicated repository.

Getting Started

The linphone-sdk project bundles Liblinphone and its dependencies as git submodules, in the purpose of simplifying the compilation and packaging of the whole suite, comprising liblinphone, mediastreamer2, belle-sip, ortp and many others.
The submodules that are not developed or maintained by the Linphone team are grouped inside the external/ directory.
The currently supported platforms are Android, iOS, Desktop (Linux, Windows, Mac OS X).

For further information, select your target of choice below:

API Reference

Full API documentation is available for all of our supported languages:

License

Linphone-sdk is dual licensed, and is available either :

  • under a GNU Affero GPLv3 license, for free (open source). Please make sure that you understand and agree with the terms of this license before using it.
  • under a proprietary license, for a fee, to be used in closed source applications. Contact Belledonne Communications for any question about costs and services.

Features

General

  • SIP user agent that is compliant with RFC 3261 (IPv6-ready)
  • user authentication via digest (SHA256 or md5), TLS client certificates, bearer (oAuth2 – OpenID Connect)
  • multiple SIP account support: registrar, proxies, outbound proxies
  • interoperability with IMS networks
  • SIP/UDP, SIP/TCP, SIP/TLS

Calling features

  • Supports multiple calls simultaneously with call management features: call hold with music, resume, blind and attended transfer, etc.
  • ICE (RFC 5245), STUN and TURN (RFC 5766) for optimised NAT traversal allowing peer-to-peer audio and video connections whenever possible
  • DTMF (telephone tone) support using SIP INFO or RFC 4733
  • Call recording (audio and video)
  • Real-time Text support (RTT),
  • HD audio calls with support for Opus
  • Other audio codecs: G729, G711, speex, gsm, AMR, AMR-WB, g722, BV16, Codec2
  • HD video calls with support for H.264, H.265, AV1 and VP8 codecs
  • State-of-the-art audio and video quality thanks to innovative algorithms:
    • 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
    • Forward Error Correction (FEC) support for video stream
    • RTCP PLI, SLI
    • Video codec selection algorithm based on platforms’ capabilities

Secure communications

  • support for various encryption protocols: SRTP-SDES, DTLS-SRTP and ZRTP
  • end-to-end media encryption with Man-in-the-middle detection using ZRTP
  • End-to-end encryption for audio/video conferences
  • Linphone Instant Messaging Encryption (LIME): end-to-end encryption with the implementation of the Double Ratchet Algorithm and Perfect Forward Secrecy
  • post quantum encryption using Crystals-Kyber algorithm
  • Encrypted Virtual file system (VFS): all data locally stored by the application are encrypted

Conferencing

Linphone-sdk offers the following features leveraging Flexisip conference server:

  • Audio/Video Group calling, up to 50 participants (with video)
  • Meetings scheduling with participants’ selection and invitations (ICS)
  • Three display modes: active speaker, mosaic, and audio only
  • Instant Messaging  and file sharing within the conference
  • Screen sharing (from desktop OS only)
  • based on a modern Selective Forwarding Unit (SFU)
  • broadcast mode with speakers and listeners

Without any conferencing server, Liblinphone supports client-mixed audio conferencing (by merging calls).

Implemented standards

Linphone-sdk implements the below specifications, grouped by topic.

SIP 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
  • 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
  • Re-INVITE and Target-Refresh Request Handling, RFC 6141, chpt. 5 only
  • Reliability of Provisional Responses in the Session Initiation Protocol (SIP), RFC 3262
  • Push Notification with the Session Initiation Protocol (SIP), RFC 8599
  • Session Description Protocol (SDP) Capability Negotiation, RFC 5939
  • SIP-specific event notification, RFC 6665
  • A Session Initiation Protocol (SIP) Event Package for Conference State - RFC 4575

Media transport

  • RTP: A transport protocol for real-time applications, RFC 3550
  • Extended RTP Profile for Real-time Transport Control Protocol (RTCP)-Based Feedback (RTP/AVPF), RFC 4585
  • Codec Control Messages in the RTP Audio-Visual Profile with Feedback (AVPF), RFC 5104
  • 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
  • Negotiating Media Multiplexing Using the Session Description Protocol (SDP), RFC8843
  • RTP Header Extension for the RTP Control Protocol (RTCP) Source Description Items, RFC 7941
  • A General Mechanism for RTP Header Extensions, RFC 8285
  • RTP Payload for Text Conversation RFC 4103
  • A Real-time Transport Protocol (RTP) Header Extension for Client-to-Mixer Audio Level Indication, RFC 6464
  • A Real-time Transport Protocol (RTP) Header Extension for Mixer-to-Client Audio Level Indication, RFC 6465

Security and encryption

  • The Session Initiation Protocol (SIP) Digest Access Authentication Scheme, RFC 8760
  • The Transport Layer Security (TLS) Protocol Version 1.3, RFC 8446
  • The Secure Real-time Transport Protocol (SRTP), RFC 3711
  • AES-GCM Authenticated Encryption in the Secure Real-time Transport Protocol (SRTP), RFC 7714
  • Datagram Transport Layer Security (DTLS) Extension to Establish Key for the Secure Real-time Transport Protocol (SRTP), RFC 5764
  • ZRTP: Media Path Key Agreement for Unicast Secure RTP, RFC 6189 
  • Double Encryption Procedures for the Secure Real-Time Transport Protocol (SRTP) - RFC 8723

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

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

Contacts

  • vCard 4.0, RFC 6350 
  • vCard Format Extensions: Place of Birth, Place and Date of Death, RFC 6474
  • CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV), RFC 6352

Knowledge base

Various subjects are covered through articles listed below.