Merge branch 'master' into ios.x264.2

Author: JohanBlome

.github/workflows/build.yml

@@ -38,4 +38,4 @@ jobs:
         with:
           api-level: ${{ matrix.api-level }}
           script: |
-            ./gradlew build
+            ./gradlew buildDefaultDebug

Makefile

@@ -14,14 +14,14 @@ test:
 
 
 verify: /tmp/akiyo_qcif.y4m
-	./scripts/encapp_verify.py -i /tmp/akiyo_qcif.y4m -ddd
+	./scripts/encapp_verify.py -i /tmp/akiyo_qcif.y4m 
 
 
 build:
 	./gradlew build
 
 install:
-	./gradlew installDebug
+	./gradlew installDefaultDebug
 
 clean:
 	./gradlew clean

README.dev.md

@@ -7,42 +7,75 @@ For a description on how to use the tool, check [README.md](README.md).
 
 # 1. Prerequisites
 
-In order to do encapp development, you need:
-* android sdk setup and environment variables set
-* android ndk
+## 1.1. Required Tools
 
-Please note that since JDK 16 gradle versions < 7 are broken.
-This means that a JDK version >= 16 must be used for building.
+To develop encapp, you need the following tools installed:
 
+### Android Development Tools
+adb push out/target/product/diamond/testcases/libmc2_tests/arm64/libmc2_tests /data/
 
-# 2. Operation
+* **Android SDK** - Android Software Development Kit with environment variables properly set
+  - Set `ANDROID_HOME` or `ANDROID_SDK_ROOT` environment variable
+  - Add platform-tools to your PATH
+* **Android NDK** - Native Development Kit for C/C++ code compilation
+  - Required for building native components
+* **Gradle** - Build automation tool (version 7.0 or higher)
+  - Bundled with the project via Gradle Wrapper (`gradlew`)
 
-## 2.1. set up the android SDK and NDK in the `local.properties` file.
+### Java Development Kit
 
-Create a `local.properties` file with valid entries for the `ndk.dir` and
-`sdk.dir` variables.
+* **JDK 16 or higher** - Required for building with Gradle 7+
+  - **Important:** Gradle versions < 7 are broken with JDK 16+
+  - Verify installation: `java -version`
+
+### Additional Tools
+
+* **Protocol Buffer Compiler (protoc)** - Optional, only needed if modifying `.proto` files
+  - Installation: See [main README section 1.1](README.md#11-external-tool-dependencies)
+* **Python 3.9+** - For running scripts and tests
+  - Installation: See [main README section 1.2](README.md#12-python-dependencies)
+
+## 1.2. iOS Development (Optional)
+
+For iOS development, you additionally need:
+
+* **Xcode** - Apple's IDE with iOS SDK
+* **Command Line Tools** - Install via `xcode-select --install`
+* **Valid iOS provisioning profile** - For device deployment
 
-```
-$ cat local.properties
-ndk.dir: /opt/android_ndk/android-ndk-r19/
-sdk.dir: /opt/android_sdk/
-```
 
-Note that this file should not be added to the repo.
+# 2. Building encapp
 
-## 2.2. build the encapp app
+## 2.1. Set up Android SDK and NDK
 
+Create a `local.properties` file in the project root with valid entries for the `ndk.dir` and `sdk.dir` variables:
+
+```properties
+ndk.dir=/opt/android_ndk/android-ndk-r19/
+sdk.dir=/opt/android_sdk/
 ```
+
+**Note:** This file should not be added to version control (it's already in `.gitignore`).
+
+## 2.2. Build the encapp App
+
+Build the Android application using Gradle:
+
+```bash
 $ ./gradlew clean
 $ ./gradlew build
 ...
 BUILD SUCCESSFUL in 6s
 61 actionable tasks: 5 executed, 56 up-to-date
 ```
 
-## 2.3. run the `setup.sh` script to install encapp in your android device.
+The APK will be generated in `app/build/outputs/apk/debug/`.
 
-```
+## 2.3. Install Using setup.sh Script
+
+The `setup.sh` script builds and installs encapp on all connected devices:
+
+```bash
 $ ./setup.sh
 ...
 Installing APK 'com.facebook.encapp-v1.0-debug.apk' on 'Pixel - 10' for app:debug
@@ -52,21 +85,33 @@ BUILD SUCCESSFUL in 14s
 31 actionable tasks: 3 executed, 28 up-to-date
 ```
 
-## 2.4. run a quick encoding experiment with the app
+## 2.4. Manual Installation and Testing
 
-Install the app.
-```
+Alternatively, manually install and test the app:
+
+```bash
+# Install the APK
 $ adb install ./app/build/outputs/apk/debug/com.facebook.encapp-v1.0-debug.apk
-$ adb shell cmd package list package |grep encapp
+
+# Verify installation
+$ adb shell cmd package list package | grep encapp
 package:com.facebook.encapp
 ```
 
-Run the `list_codecs` function.
+### Running Direct Tests
 
-Note that, for the very first time you run the instrumentation codecs, the
-device will ask you for permission to access to `/sdcard/`.
+You can test encapp functionality directly using `adb` commands without the Python script.
 
-Figure 1 shows ![an android device asking for permission to run encapp](doc/encapp_permission.jpeg)
+**List Available Codecs:**
+
+```bash
+$ adb shell am start -W -e list_codecs a -e ui_hold_sec 3 com.facebook.encapp/.MainActivity
+```
+
+**Note:** The first time you run encapp, the device will ask for permission to access `/sdcard/`.
+
+![Android device asking for permission to run encapp](doc/encapp_permission.jpeg)
+*Figure 1: Permission dialog on first run*
 
 ```
 $ adb shell am start -W -e list_codecs a -e ui_hold_sec 3 com.facebook.encapp/.MainActivity
@@ -151,50 +196,119 @@ $ adb shell cat /sdcard/codecs.txt
 ...
 ```
 
-## 3. Regression test
+# 3. Regression Testing
 
-**NOTE: this is currently not working properly, it will be adressed.**
+**NOTE: This is currently not working properly and will be addressed in a future update.**
 
-encapp_verify.py will run through the tests defined in 'tests/' folder and try to verify:
-* bitrate
-* key frames
-* temporal layers
-* long temporal references (Qualcomm ltr)
+The `encapp_verify.py` script runs through tests defined in the `tests/` folder and verifies:
+* Bitrate conformance
+* Key frame intervals
+* Temporal layer configuration
+* Long term references (LTR) - Qualcomm specific
 
-Just like encapp.py overrides for input and encoder are available.
-Run the test just like they are defined:
+## 3.1. Basic Usage
 
+Run all tests with default configuration:
+
+```bash
+$ ./scripts/encapp_verify.py
 ```
-$ encapp_verify.py
-```
 
-Override the input, encoding resolution and codec:
+## 3.2. Override Options
+
+Override input, encoding resolution, and codec:
+
+```bash
+$ ./scripts/encapp_verify.py \
+  -i /media/data/media_encapp/<encoded>.mp4 \
+  -os 1920x1080 \
+  -c encoder.avc
 ```
-$ encapp_verify.py -i /media/johan/data/media_encapp/<encoded>.mp4  -os 1920x1080 -c encoder.avc
+
+**Note:** This currently only works for encoded files, not raw files.
+
+## 3.3. Run Specific Test
+
+Override input and run a specific test:
+
+```bash
+$ ./scripts/encapp_verify.py \
+  -i /tmp/KristenAndSara_1280x720_60.yuv \
+  -is 1280x720 \
+  -if 30 \
+  -os 1280x720 \
+  -of 30 \
+  -t <PATH>/encapp/tests/simple.qcif.json
 ```
-This only works (for now) for encoded files and not raw files.
 
-Override input and run specific test:
+**Important:** For raw input, both input and output resolution and fps must be specified, even though raw buffer encoding doesn't allow scaling (surface encoding does support scaling).
+
+
+# 4. System and Unit Testing
+
+encapp includes both unit tests and system tests to ensure code quality and functionality.
+
+## 4.1. Running All Tests
+
+Run all tests using pytest:
+
+```bash
+$ python3 -m pytest PATH_TO_REPO/encapp/scripts/tests/
 ```
-$ encapp_verify.py -i /tmp/KristenAndSara_1280x720_60.yuv -is 1280x720 -if 30 -os 1280x720 -of 30 -t <PATH>/encapp/tests/simple.qcif.json
+
+## 4.2. Test Types
+
+### Unit Tests
+* Can be run without a device connected
+* Test individual components and functions in isolation
+* Fast execution
+
+### System Tests
+* **Require a device connected**
+* Test end-to-end functionality with actual hardware
+* Requirements:
+  - H.264 encoder and decoder support
+  - Surface texture support
+
+Set the target device:
+```bash
+$ export ANDROID_SERIAL=XXX
 ```
 
-For a raw input both input and output resolution and fps needs to be specified even if raw buffer will not allow scaling (which surface encoding does).
+## 4.3. Test Configuration
 
+### Automatic Installation
 
-## 4. System/Unit testing
-All current tests can be run with:
-python3 -m pytest PATH_TO_REPO/encapp/scripts/tests/
+By default, the latest build will be automatically installed on the device before running tests.
 
-* The unit tests can be run without a device connected.
-* The system tests require a device connected. To pass all tests there needs to be a h264 encodera and decoder. It also needs to have surface textures available.
+### Using Existing Installation
+
+To run tests using the currently installed application without reinstalling:
+
+```bash
+$ export ENCAPP_ALWAYS_INSTALL=0
 ```
-$ export ANDROID_SERIAL=XXX
+
+This is useful for:
+- Faster test iterations during development
+- Testing a specific installed version
+- Avoiding repeated installations on slow devices
+
+## 4.4. Running Specific Tests
+
+Run tests from a specific file:
+```bash
+$ python3 -m pytest scripts/tests/test_specific.py
 ```
 
-By default the latest build will be installed on the device. Test can also be run using the currently installed application by setting:
+Run a specific test function:
+```bash
+$ python3 -m pytest scripts/tests/test_specific.py::test_function_name
 ```
-$ export ENCAPP_ALWAYS_INSTALL=0
+
+Run with verbose output:
+```bash
+$ python3 -m pytest -v scripts/tests/
 ```
 ## 5. native modules