Android

Last modified by Simon Morlat on 2024/01/29 10:36
Contents

Using Liblinphone

Don't forget to check out or tutorials : https://gitlab.linphone.org/BC/public/tutorials

Requirements

Fisrt of all, install the Android SDK from the official site. Then run the android binary and install the following:

  • Android SDK Tools
  • Android SDK Platform-tools
  • Android SDK Build-tools
  • An Android SDK platform

Please take an eye on the README and ChangeLog files from the git repo in order to make sure to have always up to date information about the project.

Note that the README provide detailed instructions to compile the linphone app and liblinphone SDK, which is not required to simply use the SDK in your own app.

Create your project

Create a directory for your new project, then, create your project. You can either use the assistant from your IDE (Eclipse or Android Studio), or the command line:

android create project -n [project_name] -t [target_android_version] -p [path_to_project_dir] -k [package_name] -a [default_activity_name]

If you do create your project using the command line, you can still import it in your IDE.
For Eclipse , go to File -> Import -> Android - Existing Android Code Into Workspace.

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 {
    name "linphone.org maven repository"
    url "https://linphone.org/maven_repository/"
    content {
        includeGroup "org.linphone"
   }
}

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:5.3+"
releaseImplementation "org.linphone:linphone-sdk-android:5.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

For the no-video builds, use

debugImplementation "org.linphone.no-video:linphone-sdk-android-debug:5.3+"
releaseImplementation "org.linphone.no-video:linphone-sdk-android:5.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:5.3+"
releaseImplementation "org.linphone.minimal:linphone-sdk-android:5.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.

4.5.x release is the last one that will support it.

debugImplementation "org.linphone.legacy:linphone-sdk-android-debug:4.5+"
releaseImplementation "org.linphone.legacy:linphone-sdk-android:4.5+"

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.

Use a private maven repository

If you are using a private maven repository, here's how to configure and use it:

maven {
  credentials  {
    username "<user>"
    password "<password>"
 }

  authentication {
    basic(BasicAuthentication)
 }

  name "<Maven repository name>"
  url "<maven repository url>"

  content {
    includeGroup "org.linphone"
 }
}

Download our SDK (not recommended)

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') This was the old way and still works but you'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 !

Using liblinphone API

The JAVA reference API documentation is browsable here.

You can also download the source code of Linphone Android (see the Source Code on this page).

Finally a bunch of tutorials are available.

SDK 5.0 and newer features

Automatic iterate()

The newly added auto iterate mode is enabled by default on Android & iOS, but you can disable it with either core.setAutoIterateEnabled(false) method.

You can also configure that behavior in the config file like this:

[misc]
auto_iterate=0

If you forgot to disable it in the Core and you kept your existing code for scheduling the iterate nevermind, it will be of no consequence.

Foreground / Background modes

Previously developpers had to create code to detect whether the app was in foreground or background and call core.enterBackground() or core.enterForeground() accordingly.

This is no longer required as the liblinphone will do it by itself.

Service

We have always recommended Android developpers to create a Service to ensure the Core would be kept alive even if your app was in background, at least during a call.

Now we provide a sample Service named CoreService that you can extend and if needed override the following three methods:

  • createServiceNotificationChannel()
  • showForegroundServiceNotification()
  • hideForegroundServiceNotification()

These methods are automatically called by liblinphone, and in it you should respectively: create your notification channel for Android 8+ if not done already, start the service as foreground by calling startForeground with a notification of your creation and stop the foreground service with stopForeground that will remove previously created notification.

A foreground service is mandatory to ensure your app won't be killed in background during a call !

If you don't override the above methods, the CoreService will create a default channel and notification for you. For more information about how to override the channel and notification values, check the CoreService.java class in liblinphone.

For this Service to be enabled, if you overrode it you probably have declared your implementation in your Manifest.xml file.

If you wish to directly use our implementation, don't forget to declare it in your Manifest:

<service
   android:name="org.linphone.core.tools.service.CoreService"
   android:foregroundServiceType="phoneCall"
   android:stopWithTask="false"
   android:label="@string/app_name">
</service>

Audio focus

Correct handling of audio focus as also been added to liblinphone, from the ringtone to the calls and also for echo tester & echo canceller calibration.

It is completely automatic, you only need to add the following dependency in your app's build.gradle file (and maybe remove any code in your app you may already have to do that):

dependencies {
  implementation 'androidx.media:media:1.2.0'
}

Please note that our implementation will detect lost audio focus (for example a GSM call or another VoIP application call) in which case any active call will be paused.

 To disable the automatical call pausing upon loss of audio focus, set the following in your factory rc:

[audio]
android_pause_calls_when_audio_focus_lost=0

If you prefer to handle audio focus in your app, you can disable linphone-sdk audio focus management using the following configuration:

[audio]
android_disable_audio_focus_requests=1

Device ringtone

In addition of auto focus described above, we also added an API to play the user's device ringtone.

This feature is enabled by default on Android platform.

To disable it, call core.setNativeRingingEnabled(false).

You can also do it in the configuration file:

[sound]
use_native_ringing=0

Compile your app and run

Nothing specific to do, just compile it as a normal Android application (on Eclipse, right click on the project -> Run as -> Android Application).

Troubleshooting

Activate debug traces using Factory.instance().setDebugMode(true, "appName");

To get debug traces from adb:
adb logcat 

To get symbolicated stack trace from adb, use:
adb logcat -d | ndk-stack -sym ./libs-debug/`adb shell getprop ro.product.cpu.abi | tr -d '\r'`