Android sdk (#11)

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -25,6 +25,7 @@ body:
         - C
         - Python
         - Web
+        - Android
     validations:
       required: true
   - type: input

.github/workflows/android-appcenter.yml

@@ -0,0 +1,133 @@
+name: Android AppCenter Tests
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+    paths:
+      - 'binding/android/FalconTestApp/**'
+      - '.github/workflows/android-appcenter.yml'
+      - 'resources/audio_samples/**'
+  pull_request:
+    branches: [ main, 'v[0-9]+.[0-9]+' ]
+    paths:
+      - 'binding/android/FalconTestApp/**'
+      - '.github/workflows/android-appcenter.yml'
+      - 'resources/audio_samples/**'
+
+defaults:
+  run:
+    working-directory: binding/android/FalconTestApp
+
+jobs:
+  build:
+    name: Run Android Tests on AppCenter
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Node.js LTS
+        uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+
+      - name: Install AppCenter CLI
+        run: npm install -g appcenter-cli
+
+      - name: set up JDK 11
+        uses: actions/setup-java@v3
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+
+      - name: Copy test_resources
+        run: ./copy_test_resources.sh
+
+      - name: Inject AccessKey
+        run: echo pvTestingAccessKey="${{secrets.PV_VALID_ACCESS_KEY}}" >> local.properties
+
+      - name: Inject Android keystore variables
+        run: |
+          echo storePassword="${{secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD}}" >> local.properties
+          echo keyPassword="${{secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD}}" >> local.properties
+          echo keyAlias=picovoice >> local.properties
+          echo storeFile=../picovoice.jks >> local.properties
+
+      - name: Setup Android keystore file
+        run: echo "${{secrets.ANDROID_RELEASE_KEYSTORE_FILE_B64}}" | base64 -d > picovoice.jks
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Build app
+        run: ./gradlew assembleDebug
+
+      - name: Build androidTest
+        run: ./gradlew assembleDebugAndroidTest
+
+      - name: Run tests on AppCenter
+        run: appcenter test run espresso
+          --token ${{secrets.APPCENTERAPITOKEN}}
+          --app "Picovoice/Falcon-Android"
+          --devices "Picovoice/android-min-max"
+          --app-path falcon-test-app/build/outputs/apk/debug/falcon-test-app-debug.apk
+          --test-series "falcon-android"
+          --locale "en_US"
+          --build-dir falcon-test-app/build/outputs/apk/androidTest/debug
+
+  build-integ:
+    name: Run Android Integration Tests on AppCenter
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Node.js LTS
+        uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+
+      - name: Install AppCenter CLI
+        run: npm install -g appcenter-cli
+
+      - name: set up JDK 11
+        uses: actions/setup-java@v3
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+
+      - name: Copy test_resources
+        run: ./copy_test_resources.sh
+
+      - name: Inject AccessKey
+        run: echo pvTestingAccessKey="${{secrets.PV_VALID_ACCESS_KEY}}" >> local.properties
+
+      - name: Inject Android keystore variables
+        run: |
+          echo storePassword="${{secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD}}" >> local.properties
+          echo keyPassword="${{secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD}}" >> local.properties
+          echo keyAlias=picovoice >> local.properties
+          echo storeFile=../picovoice.jks >> local.properties
+
+      - name: Setup Android keystore file
+        run: echo "${{secrets.ANDROID_RELEASE_KEYSTORE_FILE_B64}}" | base64 -d > picovoice.jks
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Build app
+        run: ./gradlew assembleRelease
+
+      - name: Build androidTest
+        run: ./gradlew assembleReleaseAndroidTest -DtestBuildType=integ
+
+      - name: Run tests on AppCenter
+        run: appcenter test run espresso
+          --token ${{secrets.APPCENTERAPITOKEN}}
+          --app "Picovoice/Falcon-Android"
+          --devices "Picovoice/android-min-max"
+          --app-path falcon-test-app/build/outputs/apk/release/falcon-test-app-release.apk
+          --test-series "falcon-android"
+          --locale "en_US"
+          --build-dir falcon-test-app/build/outputs/apk/androidTest/release

.github/workflows/android-demos.yml

@@ -0,0 +1,35 @@
+name: Android Demos
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/android-demos.yml'
+      - 'demo/android/**'
+      - '!demo/android/FalconDemo/README.md'
+  pull_request:
+    branches: [ main, 'v[0-9]+.[0-9]+' ]
+    paths:
+      - '.github/workflows/android-demos.yml'
+      - 'demo/android/**'
+      - '!demo/android/FalconDemo/README.md'
+
+jobs:
+  build-falcon-demo:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: demo/android/FalconDemo
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: set up JDK 11
+        uses: actions/setup-java@v3
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+
+      - name: Build
+        run: ./gradlew assembleDebug

.github/workflows/android-perf.yml

@@ -0,0 +1,95 @@
+name: Android Performance
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+    paths:
+      - 'lib/android/**'
+      - 'lib/common/**'
+      - '.github/workflows/android-perf.yml'
+  pull_request:
+    branches: [ main, 'v[0-9]+.[0-9]+' ]
+    paths:
+      - 'lib/android/**'
+      - 'lib/common/**'
+      - '.github/workflows/android-perf.yml'
+
+defaults:
+  run:
+    working-directory: binding/android/FalconTestApp
+
+jobs:
+  build:
+    name: Run Android Speed Tests on AppCenter
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        device: [single-android, 32bit-android]
+        include:
+          - device: single-android
+            initPerformanceThresholdSec: 1.0
+            procPerformanceThresholdSec: 1.0
+          - device: 32bit-android
+            initPerformanceThresholdSec: 1.0
+            procPerformanceThresholdSec: 7.0
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v3
+
+      - name: Install AppCenter CLI
+        run: npm install -g appcenter-cli
+
+      - name: set up JDK 11
+        uses: actions/setup-java@v3
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+
+      - name: Copy test_resources
+        run: ./copy_test_resources.sh
+
+      - name: Inject AccessKey
+        run: echo pvTestingAccessKey="${{secrets.PV_VALID_ACCESS_KEY}}" >> local.properties
+
+      - name: Inject Android keystore variables
+        run: |
+          echo storePassword="${{secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD}}" >> local.properties
+          echo keyPassword="${{secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD}}" >> local.properties
+          echo keyAlias=picovoice >> local.properties
+          echo storeFile=../picovoice.jks >> local.properties
+
+      - name: Setup Android keystore file
+        run: echo "${{secrets.ANDROID_RELEASE_KEYSTORE_FILE_B64}}" | base64 -d > picovoice.jks
+
+      - name: Inject Number of Iterations
+        run: echo numTestIterations="20" >> local.properties
+
+      - name: Inject Init Performance Threshold
+        run: echo initPerformanceThresholdSec="${{ matrix.initPerformanceThresholdSec }}" >> local.properties
+
+      - name: Inject Proc Performance Threshold
+        run: echo procPerformanceThresholdSec="${{ matrix.procPerformanceThresholdSec }}" >> local.properties
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Build app
+        run: ./gradlew assembleDebug
+
+      - name: Build androidTest
+        run: ./gradlew assembleDebugAndroidTest -DtestBuildType=perf
+
+      - name: Run tests on AppCenter
+        run: appcenter test run espresso
+          --token ${{secrets.APPCENTERAPITOKEN}}
+          --app "Picovoice/Falcon-Android"
+          --devices "Picovoice/${{ matrix.device }}"
+          --app-path falcon-test-app/build/outputs/apk/debug/falcon-test-app-debug.apk
+          --test-series "falcon-android"
+          --locale "en_US"
+          --build-dir falcon-test-app/build/outputs/apk/androidTest/debug

README.md

@@ -27,13 +27,15 @@ Falcon is an on-device speaker diarization engine. Falcon is:
   - [What is Speaker Diarization?](#what-is-speaker-diarization)
   - [AccessKey](#accesskey)
   - [Demos](#demos)
-    - [Python Demos](#python-demos)
-    - [C Demos](#c-demos)
-    - [Web Demos](#web-demos)
+    - [Python Demo](#python-demo)
+    - [C Demo](#c-demo)
+    - [Web Demo](#web-demo)
+    - [Android Demo](#android-demo)
   - [SDKs](#sdks)
     - [Python](#python)
     - [C](#c)
     - [Web](#web)
+    - [Android](#android)
   - [Releases](#releases)
   - [FAQ](#faq)
 
@@ -56,7 +58,7 @@ AccessKey also verifies that your usage is within the limits of your account. Ev
 
 ## Demos
 
-### Python Demos
+### Python Demo
 
 Install the demo package:
 
@@ -74,7 +76,7 @@ Replace `${ACCESS_KEY}` with yours obtained from Picovoice Console.
 
 For more information about Python demos go to [demo/python](./demo/python).
 
-### C Demos
+### C Demo
 
 Build the demo:
 
@@ -88,7 +90,7 @@ Run the demo:
 ./demo/c/build/falcon_demo -a ${ACCESS_KEY} -l ${LIBRARY_PATH} -m ${MODEL_PATH} ${AUDIO_PATH}
 ```
 
-### Web Demos
+### Web Demo
 
 From [demo/web](demo/web) run the following in the terminal:
 
@@ -106,6 +108,12 @@ npm run start
 
 Open `http://localhost:5000` in your browser to try the demo.
 
+### Android Demo
+
+Using Android Studio, open [demo/android/FalconDemo](./demo/android/FalconDemo) as an Android project and then run the application.
+
+Replace `"${YOUR_ACCESS_KEY_HERE}"` in the file [MainActivity.java](./demo/android/FalconDemo/falcon-demo-app/src/main/java/ai/picovoice/falcondemo/MainActivity.java) with your `AccessKey`.
+
 ## SDKs
 
 ### Python
@@ -217,6 +225,43 @@ console.log(segments);
 
 Replace `${ACCESS_KEY}` with yours obtained from [Picovoice Console](https://console.picovoice.ai/). Finally, when done release the resources using `falcon.release()`.
 
+### Android
+
+To include the Falcon package in your Android project, ensure you have included `mavenCentral()` in your top-level `build.gradle` file and then add the following to your app's `build.gradle`:
+
+```groovy
+dependencies {
+    implementation 'ai.picovoice:falcon-android:${LATEST_VERSION}'
+}
+```
+
+Create an instance of the engine and perform speaker diarization on an audio file:
+
+```java
+import ai.picovoice.falcon.*;
+
+final String accessKey = "${ACCESS_KEY}"; // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
+try {
+    Falcon falcon = new Falcon.Builder()
+        .setAccessKey(accessKey)
+        .build(appContext);
+
+        File audioFile = new File("${AUDIO_FILE_PATH}");
+        FalconSegment[] segments = falcon.processFile(audioFile.getAbsolutePath());
+
+} catch (FalconException ex) { }
+```
+
+Replace `${ACCESS_KEY}` with yours obtained from Picovoice Console, and `${AUDIO_FILE_PATH}` with the path to the audio file.
+
+Finally, when done make sure to explicitly release the resources:
+
+```java
+falcon.delete()
+```
+
+For more details, see the [Android SDK](./binding/android/README.md).
+
 ## Releases
 
 ### v1.0.0 — November 28th, 2023

binding/android/Falcon/.gitignore

@@ -0,0 +1,12 @@
+*.iml
+.gradle
+/local.properties
+/.idea/
+.DS_Store
+/build
+/captures
+test_resources
+.settings
+.classpath
+.project
+publish-mavencentral.gradle