Expand Android Getting Started documentation

README.md

@@ -11,7 +11,7 @@
 The PJSIP docs at **https://docs.pjsip.org** is hosted by the *Read the Docs* (RTD) service. It contains:
 1. reference manuals (was at [pjsip.org/docs/latest/...](https://www.pjsip.org/docs/latest/pjlib/docs/html/index.htm)
 2. pjsua2 book (was at [pjsip.org/docs/book-latest](https://www.pjsip.org/docs/book-latest/html/index.html))
-3. (in progress) wiki (previously at https://trac.pjsip.org/repos/) 
+3. wiki (previously at https://trac.pjsip.org/repos/) 
 
 The PJSIP's RTD settings page is at https://readthedocs.org/projects/pjsip/. This page controls various aspects of the RTD page. Some will be explained below.
 
@@ -381,7 +381,7 @@ You need at least Doxygen 1.8.1 because Doxygen 1.5.1 is not suitable for Breath
 
 #### 2. Install Python
 
-We need Python version 3.7 or newer. It's also recommended co create `virtualenv` environment to avoid cluttering your main Python installation.
+We need Python version 3.7 or newer. It's also recommended to create `virtualenv` environment to avoid cluttering your main Python installation.
 
 #### 3. Clone pjproject_docs with the submodules
 
@@ -412,6 +412,13 @@ $ sphinx-build --version
 $ breathe-apidoc --version
 ```
 
+Below are the versions in my installations, just for reference:
+
+```
+1.9.1
+sphinx-build 5.1.0
+Breathe (breathe-apidoc) 4.34.0
+```
 
 #### 6. Generate documentation locally
 
@@ -420,7 +427,7 @@ Follow instructions in [Generating documentation locally](#generating-documentat
 #### 7. Serving the documentation
 
 ```sh
-$ cd pjproject_docs
+$ cd docs/build/html
 $ python -m http.server
 ```
 

count-keywords.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Usage:
+#  cat KEYWORDS | check-keywords.sh
+
+echo "#files  #matches keywords"
+echo "--------------------------------------"
+
+while read -r line; do
+    file_count=`grep -iwl --no-filename "$line" *.rst | wc -l`
+    word_count=`grep -iw --no-filename "$line" *.rst | wc -l`
+    echo -e "$file_count\t$word_count\t $line"
+done | sort -nr
+

docs/source/api/pjlib/index.rst

@@ -182,3 +182,8 @@ Application Microframework
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 - :doc:`main() </api/generated/pjlib/group/group__PJ__APP__OS>`
 
+
+Unit Testing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- :doc:`Unit Testing Framework </api/generated/pjlib/group/group__PJ__UNITTEST>`
+

docs/source/api/pjmedia/pjmedia-audiodev.rst

@@ -98,13 +98,23 @@ like this::
 
 .. _opensl:
 
-Android OpenSL
+Android OpenSL (deprecated)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Note that Android OpenSL ES has been deprecated in favor of :ref:`oboe`.
+
+
 .. _jnisound:
 
 Android JNI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The JNI sound device implementation is the default audio device for Android. It is accessing
+Android Java API `AudioTrack <https://developer.android.com/reference/android/media/AudioTrack>`__ and
+`AudioRecord <https://developer.android.com/reference/android/media/AudioRecord>`__ via JNI.
+
+The JNI sound device device implementation was kindly donated by `Regis Montoya <https://www.r3gis.fr>`__
+from his `CSIPSimple <https://code.google.com/p/csipsimple/>`__ project.
+
 
 .. _oboe:
 

docs/source/api/pjsua-lib/samples.rst

@@ -11,7 +11,7 @@ PJSUA-LIB Samples
      - This small app (~200 LoC) is a fully functional SIP user agent, supporting 
        registration and audio call (P.S. you need to modify credentials in the source code to
        register). Use this sample to study the general pattern and flow of PJSUA-LIB.
-   * - `pjsua <https://github.com/pjsip/pjproject/tree/master/pjsip-apps/src/pjsua/>`_
+   * - :doc:`/samples/pjsua`
      - PJSUA-LIB
      - This is the reference implementation of PJSIP, demonstrating everything that PJSIP
        has to offer. We use this for any testing and for actual communications as well.

docs/source/api/pjsua2/samples.rst

@@ -17,10 +17,10 @@ PJSUA2 Samples
      - Simple audio conference and chatroom server
    * - :source:`Android Java Pjsua2 <pjsip-apps/src/swig/java/android>`
      - PJSUA2 (Android, Java)
-     - Java GUI application supporting audio/video calls. See :ref:`android_pjsua2`.
+     - Java GUI application supporting audio/video calls. See :doc:`/get-started/android/java-sip-client`.
    * - :source:`Android Kotlin Pjsua2 <pjsip-apps/src/swig/java/android>`
      - PJSUA2 (Android, Kotlin)
-     - Kotlin GUI application supporting audio/video calls. See :ref:`android_pjsua2`.
+     - Kotlin GUI application supporting audio/video calls. See :doc:`/get-started/android/java-sip-client`.
    * - `Java sample <https://github.com/pjsip/pjproject/tree/master/pjsip-apps/src/swig/java>`_
      - PJSUA2 (SWIG, Java)
      - This requires the Java SWIG module. After building the SWIG module, run ``make test`` 

docs/source/api/samples.rst

@@ -1,14 +1 @@
-All Samples
-===================
-.. toctree::
-   :maxdepth: 1
-
-.. include:: /api/pjsua2/samples.rst
-
-.. include:: /api/pjsua-lib/samples.rst
-
-.. include:: /api/pjsip/samples.rst
-
-.. include:: /api/pjmedia/samples.rst
-
-.. include:: /api/pjnath/samples.rst
+.. include:: /samples/index.rst

docs/source/common/common_sip_features_overview.rst

@@ -0,0 +1,8 @@
+- support for multiple SIP accounts,
+- call features such as voice and video call, call hold, call transfer, both attended and unattended,
+  call redirection,
+- protocol features such as UPDATE, 100rel, PRACK, tel: URI, Session Timers, 
+  outbound, Path header, IPv6, DNS SRV resolution,
+- NAT traversal features such as symetric transport, SIP outbound, Service-Route, ICE and trickle ICE option, 
+- presence and instant messaging,
+- security related, such as digest, AKA, AKA-v2, OAuth 2.0 authentication, TLS transport

docs/source/conf.py

@@ -92,7 +92,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'PJSIP Project'
-copyright = '2023, Teluu'
+copyright = '2025, Teluu'
 author = 'Teluu Team'
 
 # Find pjproject directory to open version.mak

docs/source/get-started/android/KEYWORDS

@@ -0,0 +1,14 @@
+android
+api
+client
+dialer
+library
+open source
+portable
+sample
+SDK
+softphone
+source code
+stack
+video call
+voip

docs/source/get-started/android/additional-guides.rst

@@ -0,0 +1,146 @@
+Creating your own application
+=======================================
+
+.. contents:: In this page:
+   :depth: 2
+   :local:
+
+
+
+.. _android_create_app:
+
+Creating your own application
+------------------------------------------
+
+Creating your own Android SIP application based on PJSIP typically involves the following steps.
+
+#. We assume that PJSIP native libraries have been built by following the previous guide in
+   :doc:`/get-started/android/build_instructions`, including the JNI (SWIG) interface.
+#. Create Android application outside the PJSIP sources for your project.
+#. Copy ``libpjsua2.so`` and ``libc++_shared.so`` to your **jniLibs/$ARCH** directory:
+
+   .. code-block:: shell
+
+      $ cd $YOUR_PROJECT_DIR/app/src/main/jniLibs
+      $ cp -r $PJSIP_DIR/pjsip-apps/src/swig/java/android/pjsua2/src/main/jniLibs/* .
+      $ ls -R
+      arm64-v8a
+
+      ./arm64-v8a:
+      libcrypto.so  libc++_shared.so  liboboe.so  libpjsua2.so  libssl.so
+
+#. You will see the third party libs (OpenSSL, Oboe) in the ``ls`` output above if you have followed the
+   previous tutorial to develop the sample Java application. If you only see ``libpjsua2.so`` and
+   ``libc++_shared.so``, follow the guide in :ref:`android_copy_3rd_party_libs`. After
+   that, you should see the **jniLibs** contents like above.
+#. Copy pjsua2 Java interface files from ``pjsip-apps/src/swig/java/android/app/src/main/java`` to your 
+   project's ``app/src/main/java`` folder, e.g:
+
+   .. code-block:: shell
+
+      $ cd $YOUR_PROJECT_DIR/app/src/main/java
+      $ cp -r $PJSIP_DIR/pjsip-apps/src/swig/java/android/app/src/main/java/* .
+
+      # check
+      $ ls
+      org
+
+      # Cleanup excess pjsua2 application sources.
+      $ rm -r org/pjsip/pjsua2/app
+
+#. Start writing your application, by following these guides:
+
+   - :doc:`pjsua2 Guide </pjsua2/intro>`
+   - :doc:`pjsua2 API reference and samples </api/pjsua2/index>`
+
+
+
+Adding Video Capture Device to Your Application
+-------------------------------------------------------
+
+Copy the java part of PJSIP Android capture device to the application's source 
+directory:
+
+.. code-block:: shell
+
+   cp pjmedia/src/pjmedia-videodev/android/PjCamera*.java [your_app]/src/org/pjsip/
+
+
+Since 2.12, the capture device uses ``Camera2`` API (see also :pr:`2797` for 
+more info), application need to configure the ``CameraManager`` instance 
+in ``PjCameraInfo2`` before using the camera, e.g:
+
+.. code-block:: java
+
+   @Override protected void onCreate(Bundle savedInstanceState)
+   {
+      //..
+      CameraManager cm = (CameraManager)getSystemService(Context.CAMERA_SERVICE);
+      PjCameraInfo2.SetCameraManager(cm);
+      //..
+   }
+
+
+
+Using Video API
+-----------------------------------
+Please check :doc:`Working with Video </pjsua2/using/media_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 callback ``onConfigurationChanged()``).
+#. 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 :pr:`1861` explains 
+this feature in detail.
+
+
+
+Installing additional components
+-----------------------------------
+
+.. _android_openh264:
+
+Installing OpenH264 (optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Note that OpenH264 is optional because native H.264 codec is already provided by :ref:`amediacodec`.
+
+#. Build OpenH264 for Android. See :ref:`openh264` for more information.
+#. Run **configure-android** with specifying OpenH264 directory, e.g.:
+
+   .. code-block:: shell
+
+      $ ./configure-android --with-openh264=/Users/me/openh264/android
+
+#. Make sure openh264 is detected:
+
+   .. code-block:: shell
+
+      ...
+      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 :pr:`1776` for more info.
+
+#. Copy all library's **.so** files into your Android application's **jniLibs/$ARCH** directory,
+   as explained in :ref:`android_copy_3rd_party_libs`. For example:
+
+   .. code-block:: shell
+
+     $ cd pjsip-apps/src/swig/java/android/pjsua2/src/main/jniLibs/arm64-v8a
+     $ cp /Users/me/openh264/android/*.so .
+
+
+