Build Instructions
Requirements
You need the Android NDK.
Optional if you want to build and and run the sample applications (i.e: pjsua2 and pjsua):
Build Preparation
Getting the source code if you haven’t already.
Set your config_site.h to the following:
/* Activate Android specific settings in the 'config_site_sample.h' */
#define PJ_CONFIG_ANDROID 1
#include <pj/config_site_sample.h>
Building PJSIP
Just run:
$ cd /path/to/your/pjsip/dir
$ export ANDROID_NDK_ROOT=/path_to_android_ndk_dir
$ ./configure-android
$ make dep && make clean && make
Tip
On MinGW32/MSys, use absolute path format D:/path/to/android/ndk
instead of /D/path/to/android/ndk
for setting ANDROID_NDK_ROOT
.
This will build armV64 target, to build for other targets such as armeabi-v7a, x86
see next section.
Supporting 16 KB page sizes (Android 15)
As described in Android’s official doc, starting from Android 15, it supports devices that are configured to use a page size of 16 KB (16 KB devices).
In order for PJSIP to support flexible page sizes (both 4 and 16 KB), you need to use NDK r27 or later and apply https://github.com/pjsip/pjproject/pull/4068. Alternatively, you can manually specify the build flags to the configure script:
CFLAGS="-D__BIONIC_NO_PAGE_SIZE_MACRO" LDFLAGS="-Wl,-z,max-page-size=16384" ./configure-android
Building for other architectures
Make sure to cleanup all existing binary and intermediate files, e.g:
$ cd /path/to/your/pjsip/dir $ make clean # cleanup pjsua sample app $ cd pjsip-apps/src/pjsua/android/jni $ make clean # also cleanup pjsua2 sample app (SWIG) $ cd /path/to/your/pjsip/dir $ cd pjsip-apps/src/swig $ make clean
Specify the target arch in
TARGET_ABI
and run it with--use-ndk-cflags
, for example:TARGET_ABI=arm64-v8a ./configure-android --use-ndk-cflags
Also you should adjust Application.mk and library packaging path (see also #1803).
Note
The
./configure-android
is a wrapper that calls the standard./configure
script with settings suitable for Android target. Standard./configure
options should be applicable to this script too.Please check
./configure-android --help
for more info.Other customizations are similar to what is explained in Building with GNU Tools/Autoconf page.
Enable Oboe
Oboe offers low latency audio and some other benefits, please check here for more info. Oboe is supported since PJSIP version 2.12. To enable Oboe, please follow steps described in #2707.
Video Support
Features
Video on Android has been supported since PJSIP version 2.4. Some of the highlighted features include:
native OpenGL ES 2.0 renderer (requires Android 2.2 (API level 8) or higher).
Requirements
OpenH264 (optional)
For general information on OpenH264 integration see OpenH264
Copy all library .so files into your Android application project directory, for example:
cp /Users/me/openh264/android/*.so /Users/me/pjproject-2.0/pjsip-apps/src/swig/java/android/libs/armeabi
libvpx (if you need VP8 or VP9 codec)
ffmpeg (optional)
AMediaCodec, native Android codecs (experimental)
Configuring
To enable video, append this into config_site.h:
#define PJMEDIA_HAS_VIDEO 1
Specify third-party video libraries when invoking ./configure-android
, e.g:
$ ./configure-android --with-openh264=/Users/me/openh264/android
Make sure openh264 is detected by ./configure-android
:
...
Using OpenH264 prefix... /Users/me/openh264/android
checking OpenH264 availability... ok
...
Note
If you use PJSIP before version 2.6, you need to specify external libyuv via
the configure script param --with-libyuv
, check #1776 for more info.
Adding Video Capture Device to Your Application
Copy the java part of PJSIP Android capture device to the application’s source directory:
cp pjmedia/src/pjmedia-videodev/android/PjCamera*.java [your_app]/src/org/pjsip/
Since 2.12, the capture device uses Camera2
API (see also #2797 for
more info), application need to configure the CameraManager
instance
in PjCameraInfo2
before using the camera, e.g:
@Override protected void onCreate(Bundle savedInstanceState)
{
//..
CameraManager cm = (CameraManager)getSystemService(Context.CAMERA_SERVICE);
PjCameraInfo2.SetCameraManager(cm);
//..
}
Using Video API
Please check Working with Video (PJSUA2 Guide).
Video capture orientation support
To send video in the proper orientation (i.e. head always up regardless of the device orientation), application needs to do the following:
Setup the application to get orientation change notification (by adding
android:configChanges="orientation|keyboardHidden|screenSize"
in the application manifest file and override the callbackonConfigurationChanged()
).Inside the callback, call PJSUA2 API
VidDevManager::setCaptureOrient()
to set the video device to the correct orientation.
For sample usage, please refer to pjsua2 sample app. Ticket #1861 explains this feature in detail.
OpenSSL Support
Build OpenSSL (tested with OpenSSL 1.0.2s) for Android. The instruction provided here is specifically for arm64. For other architectures, modify accordingly.
Please visit this page for reference and some examples.
Note
You need to change the NDK path and the API platform level below.
cd openssl-3.0.4 export ANDROID_NDK_ROOT=[your_android_ndk_path] # Change the host as required (e.g: linux -> darwin) PATH=$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin:$ANDROID_NDK_ROOT/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin:$PATH ./Configure android-arm64 -D__ANDROID_API__=29 make
Then copy the libraries into lib folder:
mkdir lib cp lib*.a lib/
Specify OpenSSL location when running
configure-android
, for example (with Bash): (change the openssl path folder)TARGET_ABI=arm64-v8a ./configure-android --use-ndk-cflags --with-ssl=[your_openssl_path]
And check that OpenSSL is detected by the configure script:
... checking for OpenSSL installations.. checking openssl/ssl.h usability... yes checking openssl/ssl.h presence... no aconfigure: WARNING: openssl/ssl.h: accepted by the compiler, rejected by the preprocessor! aconfigure: WARNING: openssl/ssl.h: proceeding with the compiler's result checking for openssl/ssl.h... yes checking for ERR_load_BIO_strings in -lcrypto... yes checking for SSL_library_init in -lssl... yes OpenSSL library found, SSL support enabled ...
Build the libraries:
make dep && make
If you encounter linking errors, you need to add this in
user.mak
:export LIBS += "-ldl -lz"
Trying our sample application and creating your own
Setting up the target device
To run or debug application (such as the sample applications below), first we need to setup the target device:
using virtual device: http://developer.android.com/tools/devices/index.html
using real device: http://developer.android.com/tools/device.html
Building and running pjsua2 sample applications (Java & Kotlin)
Sample applications using pjsua2 API with SWIG Java binding is located under pjsip-apps/src/swig/java/android. It is not built by default, and you need SWIG to build it.
Follow these steps to build pjsua2 sample applications:
Make sure SWIG is in the build environment PATH.
Run
make
from directory pjsip-apps/src/swig (note that the Android NDK root should be in the PATH), e.g:$ cd /path/to/your/pjsip/dir $ cd pjsip-apps/src/swig $ make
This step should produce:
native library
libpjsua2.so
inpjsip-apps/src/swig/java/android/pjsua2/src/main/jniLibs/arm64-v8a
Note
If you are building for other target ABI, you’ll need to manually move
libpjsua2.so
to the appropriate target ABI directory, e.g:jniLibs/armeabi-v7a
, please check here for target ABI directory names.pjsua2 Java interface (a lot of
.java
files) in pjsip-apps/src/swig/java/android/pjsua2/src/main/java/org/pjsip/pjsua2
Make sure any library dependencies are copied to
pjsip-apps/src/swig/java/android/pjsua2/src/main/jniLibs/arm64-v8a
(or the appropriate target ABI directory), e.g:libopenh264.so
for video support.Open pjsua2 project in Android Studio, it is located in pjsip-apps/src/swig/java/android. It will contain three modules: - pjsua2 Java interface: pjsip-apps/src/swig/java/android/pjsua2 - Java sample app: pjsip-apps/src/swig/java/android/app - Kotlin sample app: pjsip-apps/src/swig/java/android/app-kotlin
Run sample app.
Log output
The pjsua2 sample applications will write log messages to LogCat window.
Creating your own application
For developing Android application, you should use pjsua2 API whose Java interface available via SWIG Java binding.
First, build
pjproject
libraries as described above.Also build
pjsua2 sample application
as described above, this step is required to generate the pjsua2 Java interface and the native library.Create Android application outside the PJSIP sources for your project.
Get pjsua2 Java interface and native library from pjsua2 sample application:
Copy pjsua2 Java interface files from
`pjsip-apps/src/swig/java/android/app/src/main/java
to your project’sapp/src/main/java
folder, e.g:$ cd $YOUR_PROJECT_DIR/app/src/main/java $ cp -r $PJSIP_DIR/pjsip-apps/src/swig/java/android/app/src/main/java . # Cleanup excess pjsua2 application sources. $ rm -r org/pjsip/pjsua2/app
Copy native library
libpjsua2.so
frompjsip-apps/src/swig/java/android/app/src/main/jniLibs
to your project’sapp/src/main/jniLibs
folder:$ cd $YOUR_PROJECT_DIR/app/src/main/jniLibs $ cp -r $PJSIP_DIR/{pjsip-apps/src/swig/java/android/app/src/main/jniLibs .
Start writing your application, please check pjsua2 docs for reference.
Pjsua sample application with telnet interface
There is also the usual pjsua with telnet command line user interface, which is located under pjsip-apps/src/pjsua/android. It is not built by default and you need SWIG to build it. Application flow and user interface are handled mainly in the native level, so it doesn’t use pjsua2 API with Java interface.
Follow these steps to build pjsua:
Make sure that pjsua app is included on the build.
Call this before calling
configure-android
EXPORT EXCLUDE_APP=0
Proceed to normal build by calling
configure-android
,make dep
,make
Make sure SWIG is in the build environment PATH. Alternatively, update SWIG path in pjsip-apps/src/pjsua/android/jni/Makefile file.
Run
make
from directory pjsip-apps/src/pjsua/android/jni. The Android NDK root should be in the PATH, e.g:$ cd /path/to/your/pjsip/dir $ cd pjsip-apps/src/pjsua/android/jni $ make
Open pjsua2 app project in Android Studio, it is located in pjsip-apps/src/pjsua/android.
Run it.
You will see telnet instructions on the device’s screen. Telnet to this address to operate the application. See CLI Manual.
Kotlin Support
Have a look at #2648