Portaudio with Oboe Implementation

.gitignore

@@ -19,6 +19,10 @@ libtool
 portaudio-2.0.pc
 autom4te.cache/*
 
+# build_all_PaOboe.sh CMake output folder
+build
+build_old
+
 # Precompiled Headers
 *.gch
 *.pch
@@ -54,5 +58,7 @@ CMakeSettings.json
 # VSCode
 .vscode*
 
+# idea
+.idea*
+
 # Common build directories of users and VSCode
-build*

README.md

@@ -30,7 +30,6 @@ Please feel free to join. See http://www.portaudio.com for details.
     src/os                  = os specific (but host api neutral) code
     src/hostapi             = implementations for different host apis
 
-
 ### Host API Implementations:
 
     src/hostapi/alsa        = Advanced Linux Sound Architecture (ALSA)
@@ -40,6 +39,7 @@ Please feel free to join. See http://www.portaudio.com for details.
     src/hostapi/coreaudio   = Macintosh Core Audio for OS X
     src/hostapi/dsound      = Windows Direct Sound
     src/hostapi/jack        = JACK Audio Connection Kit
+    src/hostapi/oboe        = Oboe Library for Android (see src/hostapi/oboe/README.md)
     src/hostapi/oss         = Unix Open Sound System (OSS)
     src/hostapi/pulseaudio  = Sound system for POSIX OSes
     src/hostapi/sndio       = Small audio and MIDI framework (sndio)

build_all_PaOboe.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Script used to build Portaudio for multiple Android ABIs, useful for its Oboe host API.
+#
+# Ensure that ANDROID_NDK environment variable is set to your Android NDK location
+# e.g. /Library/Android/sdk/ndk-bundle
+
+if [ -z "$ANDROID_NDK" ]; then
+  echo "Please set ANDROID_NDK to the Android NDK folder"
+  exit 1
+fi
+
+# Build directory
+BUILD_DIR=build
+
+CMAKE_ARGS="-H. \
+  -DBUILD_SHARED_LIBS=true \
+  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+  -DANDROID_TOOLCHAIN=clang \
+  -DANDROID_STL=c++_shared \
+  -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \
+  -DCMAKE_INSTALL_PREFIX=."
+
+function build_PaOboe {
+
+  ABI=$1
+  MINIMUM_API_LEVEL=$2
+  ABI_BUILD_DIR=${BUILD_DIR}/${ABI}
+
+  echo "Building Pa_Oboe for ${ABI}"
+
+  mkdir -p ${ABI_BUILD_DIR} ${ABI_BUILD_DIR}/${STAGING_DIR}
+
+  cmake -B${ABI_BUILD_DIR} \
+        -DANDROID_ABI=${ABI} \
+        -DANDROID_PLATFORM=android-${MINIMUM_API_LEVEL}\
+        ${CMAKE_ARGS}
+
+  pushd ${ABI_BUILD_DIR}
+  make -j5
+  popd
+}
+
+#build_PaOboe armeabi-v7a 16
+build_PaOboe arm64-v8a 21
+#build_PaOboe x86 16
+build_PaOboe x86_64 21

cmake/modules/FindOboe.cmake

@@ -0,0 +1,74 @@
+#[=======================================================================[.rst:
+Findoboe
+--------
+
+Finds the oboe library. OBOE_DIRECTORY has to be set to the path of the directory where
+the oboe repository was cloned (see src/hostapi/oboe/README.md for more information).
+
+Imported Targets
+^^^^^^^^^^^^^^^^
+
+This module provides the following imported target, if found:
+
+``Oboe::oboe``
+  The OBOE library
+
+#]=======================================================================]
+
+if(NOT DEFINED OBOE_DIRECTORY)
+    #Insert the path of the directory where you cloned Oboe, i.e. ${CMAKE_CURRENT_SOURCE_DIR}/../oboe
+    set(OBOE_DIRECTORY FALSE)
+endif()
+
+if(NOT OBOE_DIRECTORY)
+    message(AUTHOR_WARNING
+            "If you're trying to use Oboe as a Host API, please specify the directory where you "
+            "cloned its repository. For further information, please read src/hostapi/oboe/README.md"
+            )
+    set(OBOE_FOUND FALSE)
+else()
+    if(NOT DEFINED OBOE_INCLUDE_DIR)
+        set(OBOE_INCLUDE_DIR ${OBOE_DIRECTORY}/include)
+    endif()
+
+    if(NOT DEFINED OBOE_LIBRARY_DIRS)
+        set(OBOE_LIBRARY_DIRS ${OBOE_DIRECTORY}/build/${ANDROID_ABI})
+    endif()
+    set(OBOE_LIBRARIES ${OBOE_LIBRARY_DIRS}/liboboe.so)
+
+    find_package(PkgConfig QUIET)
+    if(PkgConfig_FOUND)
+        pkg_check_modules(OBOE Oboe)
+    else()
+        find_library(OBOE_LIBRARIES
+                NAMES liboboe.so
+                HINTS ${OBOE_LIBRARY_DIRS}
+                DOC "Oboe Library"
+                )
+        find_path(OBOE_INCLUDE_DIR
+                NAMES oboe/Oboe.h
+                DOC "Oboe header"
+                )
+    endif()
+
+    find_library(LOG_LIBRARY log) #used by pa_oboe.cpp and pa_oboe.h as a logging tool
+
+    set(OBOE_LINK_LIBRARIES ${OBOE_LIBRARIES} ${LOG_LIBRARY})
+
+    include(FindPackageHandleStandardArgs)
+    find_package_handle_standard_args(
+            Oboe
+            DEFAULT_MSG
+            OBOE_LINK_LIBRARIES
+            OBOE_INCLUDE_DIR
+    )
+
+    if(OBOE_INCLUDE_DIR AND OBOE_LINK_LIBRARIES)
+        set(OBOE_FOUND TRUE)
+        if(NOT TARGET Oboe::oboe)
+            add_library(Oboe::oboe INTERFACE IMPORTED GLOBAL)
+            target_link_libraries(Oboe::oboe INTERFACE "${OBOE_LINK_LIBRARIES}")
+            target_include_directories(Oboe::oboe INTERFACE "${OBOE_INCLUDE_DIR}")
+        endif()
+    endif()
+endif()

include/pa_oboe.h

@@ -0,0 +1,141 @@
+/*
+ * $Id:
+ * PortAudio Portable Real-Time Audio Library
+ * Latest Version at: http://www.portaudio.com
+ *
+ * Android Oboe implementation of PortAudio.
+ *
+ ****************************************************************************************
+ *      Author:                                                                         *
+ *              Carlo Benfatti          <[email protected]>                        *
+ ****************************************************************************************
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files
+ * (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
+ * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/*
+ * The text above constitutes the entire PortAudio license; however,
+ * the PortAudio community also makes the following non-binding requests:
+ *
+ * Any person wishing to distribute modifications to the Software is
+ * requested to send the modifications to the original developer so that
+ * they can be incorporated into the canonical version. It is also
+ * requested that these non-binding requests be included along with the
+ * license above.
+ */
+
+#ifndef PA_OBOE_H
+#define PA_OBOE_H
+
+/**
+ * @file
+ * @ingroup public_header
+ * @brief Android Oboe-specific PortAudio API extension header file.
+ */
+
+#include "portaudio.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif //__cplusplus
+
+#define TIMEOUT_NS 1000000000 //Arbitrary timeout of the read/write functions
+#define LOW_LATENCY_MS 300.0 //Arbitrary value used to automatically determine if low latency performance mode is doable
+
+/**
+ * Enum class that emulates Oboe::Direction.
+ */
+enum class PaOboe_Direction: int32_t { Output = 0, Input = 1 };
+
+/**
+ * Enum class that emulates Oboe::Usage.
+ */
+enum class PaOboe_Usage : int32_t {
+    Media = 1 , VoiceCommunication = 2 , VoiceCommunicationSignalling = 3 , Alarm = 4 ,
+    Notification = 5 , NotificationRingtone = 6 , NotificationEvent = 10 , AssistanceAccessibility = 11 ,
+    AssistanceNavigationGuidance = 12 , AssistanceSonification = 13 , Game = 14 , Assistant = 16
+};
+
+/**
+ * Enum class that emulates Oboe::InputPreset
+ */
+enum class PaOboe_InputPreset : int32_t {
+    Generic = 1 , Camcorder = 5 , VoiceRecognition = 6 , VoiceCommunication = 7 ,
+    Unprocessed = 9 , VoicePerformance = 10
+};
+
+/**
+ * Enum class that emulates Oboe::PerformanceMode
+ */
+enum class PaOboe_PerformanceMode : int32_t { None = 10 , PowerSaving = 11 , LowLatency = 12 };
+
+/**
+ *  The android stream type and recording preset as defined in Oboe.
+ */
+typedef struct PaOboeStreamInfo {
+    PaOboe_Usage androidOutputUsage;
+    PaOboe_InputPreset androidInputPreset;
+} PaOboeStreamInfo;
+
+
+/**
+ * Provide PaOboe with the ID of the device the user chose - oboe cannot build a device list,
+ * but can select the device if provided with its ID.
+ * @param direction - the direction of the stream for which we want to set the device.
+ * @param deviceID - the ID of the chosen device chosen by the user.
+ */
+void PaOboe_SetSelectedDevice(PaOboe_Direction direction, int32_t deviceID);
+
+
+/**
+ * \brief   Provide PaOboe with the performance mode chosen by the user. If this method isn't called, the default mode
+ *          is LowLatency.
+ * @param   direction - the direction of the stream for which we want to set the performance mode.
+ * @param   performanceMode - the performance mode chosen by the user.
+ */
+void PaOboe_SetPerformanceMode(PaOboe_Direction direction, PaOboe_PerformanceMode performanceMode);
+
+
+/**
+ * Provide PA Oboe with native buffer information. If you call this function, you must do so before
+ * calling Pa_Initialize. To have optimal latency, this function should be called - otherwise,
+ * PA Oboe will use potentially non-optimal values as default.
+ * @param bufferSize the native buffersize as returned by AudioManager's
+ * PROPERTY_OUTPUT_FRAMES_PER_BUFFER. It is recommended you set the number of buffers to 1 if API>17
+ * as well, and use the sample rate defined in AudioManager's android.media.property.OUTPUT_SAMPLE_RATE.
+ * All three together will enable the AUDIO_OUTPUT_FLAG_FAST flag.
+ */
+void PaOboe_SetNativeBufferSize(unsigned long bufferSize);
+
+/**
+ * Provide PA Oboe with native buffer information. If you call this function, you must do so before
+ * calling Pa_Initialize. To have optimal latency and enable the AUDIO_OUTPUT_FLAG_FAST flag, this
+ * function should be called - otherwise, PA Oboe will use potentially non-optimal values (2) as default.
+ * @param buffers The number of buffers can be reduced to 1 on API >17. Make sure you set the native
+ * buffer size when doing this, and use the sample rate defined in AudioManager's
+ * android.media.property.OUTPUT_SAMPLE_RATE.
+ */
+void PaOboe_SetNumberOfBuffers(unsigned numberOfBuffers);
+
+#ifdef __cplusplus
+}
+#endif //__cplusplus
+
+#endif //PA_OBOE_H

include/portaudio.h

@@ -273,6 +273,7 @@ PaHostApiIndex Pa_GetDefaultHostApi( void );
 
  @see PaHostApiInfo
 */
+
 typedef enum PaHostApiTypeId
 {
     paInDevelopment=0, /* use while developing support for a new host API */
@@ -292,6 +293,7 @@ typedef enum PaHostApiTypeId
     paAudioIO=15,
     paPulseAudio=16,
     paSndio=17
+    paOboe=18
 } PaHostApiTypeId;
 
 

src/common/pa_hostapi.h

@@ -160,6 +160,13 @@ are defaulted to 1.
 #define PA_USE_ASIHPI 1
 #endif
 
+#ifndef PA_USE_OBOE
+#define PA_USE_OBOE 0
+#elif (PA_USE_OBOE != 0) && (PA_USE_OBOE != 1)
+#undef PA_USE_OBOE
+#define PA_USE_OBOE 1
+#endif
+
 #ifdef __cplusplus
 extern "C"
 {

src/hostapi/oboe/README.md

@@ -0,0 +1,42 @@
+# Portaudio implementation for android using Oboe.
+
+In order to use this implementation correctly, be sure to include the "portaudio.h" and "pa_oboe.h"  
+headers in your project.
+
+Building:
+----  
+To build portaudio with Oboe, there are some necessary steps:
+1) An android NDK is needed to crosscompile it. I used the version 25.1.8937393, which I found at
+   https://developer.android.com/ndk/downloads.
+2) Clone the Oboe repository - just follow the steps detailed here:
+   https://github.com/google/oboe/blob/main/docs/GettingStarted.md.
+   Make sure to correctly link the NDK path in the Oboe build. If you instead prefer to use the
+   prebuilt libraries, you can skip this step.
+3) Set the CMake variable OBOE_DIRECTORY (used in cmake/modules/FindOboe.cmake) to the path of the
+   cloned Oboe repository, and build the Oboe libraries (you can use "build_all_android.sh").
+
+   If you instead used the prebuilt libraries, do the following:
+   - set OBOE_DIRECTORY to TRUE;
+   - set OBOE_LIBRARY_DIRS path_to_Oboe_libraries_folder/${ANDROID_ABI}), the code will search the
+     prebuilt library of the chosen ABI in that folder.
+
+4) Build PaOboe (you can use "build_all_PaOboe.sh").
+5) Don't forget to add liboboe.so and libportaudio.so in your jniLibs folder.
+
+TODOs:
+----  
+- Testing. This implementation is being tested for VoIP calls that use blocking streams - for
+  everything else, lots of tests are needed.
+
+Misc
+----  
+### Audio Format:
+If you need to select a specific audio format, you'll have to manually set it in PaOboe_OpenStream 
+by modifying the format selection marked with a *FIXME*. I'm positive that automatic format selection 
+is possible, but simply using  PaUtil_SelectClosestAvailableFormat got me nowhere.
+
+
+### Buffer sizes:
+Portaudio often tries to get approximately low buffer sizes, and if you need specific sizes for your
+buffer you should manually modify it (or make a simple function that can set it). For your convenience,
+there is a *FIXME* as a bookmark.