Android Platform

Plugin Specs

Compatibility
- Unity 2018.x - 2022.x are supported (see below for build notes)
- Supported CPU architectures are arm-v7a, arm64-v8a, x86 and x86-64
- This plugin requires a minimum Android API level of 15 when using the MediaPlayer API, and API level 16 when using ExoPlayer (due to its use of MediaCodec).
Rendering
- For rendering OpenGL ES 2.0 and OpenGL ES 3.0 are supported, and multi-threaded rendering is supported on both.
- Vulkan graphics API is not yet supported
Internals
- Under the hood we’re using the Android MediaPlayer API and ExoPlayer 2.18.0 API
- The only 3rd-party libraries used are:
  - ExoPlayer 2.19.1 https://github.com/google/ExoPlayer
  - Facebook Audio 360 1.7.12 https://facebookincubator.github.io/facebook-360-spatial-workstation/
  - Secret Rabbit Code (aka libsamplerate) 0.1.9 http://www.mega-nerd.com/SRC/license.html

Supported Media

See the Supported Media section for more information.

Streaming

See the Streaming section for more information.

Platform-Specific Options

See the Platform-Specific Options section for more information.

Build Notes

Gradle must be used as the build environment. This was introduced in Unity 2017, but different versions of Unity use different versions of Gradle (as outlined here: https://docs.unity3d.com/Manual/android-gradle-overview.html). We have found that it is not possible to build an application that incorporates AVPro Video using some of the older versions of Gradle found in many of the 2017/2018 Unity releases. The following list will guide you as to what versions we have observed working, and if there are any special requirements.

   2017.1               - requires gradle change*
   2017.2               - requires gradle change*
   2017.3               - requires gradle change*
   2017.4 to 2017.4.16  - requires gradle change*
   2017.4.17 onwards    - works directly from Unity
   2018.1               - requires gradle change*
   2018.2               - requires gradle change*
   2018.3               - works directly from Unity
   2018.4               - works directly from Unity
   2019.1               - works directly from Unity
   2019.2               - works directly from Unity
   2019.3               - works directly from Unity
   2019.4               - works directly from Unity
   2020.1               - works directly from Unity
   2020.2 onwards       - see notes below

old gradle needs a toolchain in older NDK (<= 16b), old NDK does not support Java 1.8 which ExoPlayer requires compilation with.

Note

It has been seen that Unity can sometimes want to use a version of the build tools that are not on a given system. To overcome this you have to tell gradle to use a version you have on your system. In Player Settings|Publisher Settings, enable the Custom Gradle Template option. This will allow you to adjust the buildToolsVersion to one you have on your system. The template is found at: /Assets/Plugins/Android/mainTemplate.gradle

Unity 2020.1 and above

When using Unity 2020.1 and above it has been seen that the build process overly optimises which causes issues in the ExoPlayer library. To overcome this issue, you will need to add a custom gradle property. In Player Settings|Publisher Settings, enable the Custom Gradle Properties Template option. The template is found at: /Assets/Plugins/Android/gradleTemplate.properties and it should be edited adding the following line to the end of the file: android.enableDexingArtifactTransform=false

Note

As of v2.0.9 the addition of this property has been automated in a post process build script.

Unity 2022.1 and above

Exoplayer requires Android SDK 33, which does not come with this version of Unity. In Player Settings|Other Settings, set Target API Level to Android 13.0 (API level 33) and Unity should download the correct SDK when you build. The SDK will be downloaded to Editor/Data/PlaybackEngines/AndroidPlayer/SDK/platforms/.

If you need to target a lower version of Android, then you need to add a custom gradle property. In Player Settings|Publisher Settings, enable the Custom Main Gradle Template and Custom Launcher Gradle Template options. The templates are found at: /Assets/Plugins/Android/mainTemplate.gradle and /Assets/Plugins/Android/launcherTemplate.gradle and they should be edited by adding the following lines:

minSdkVersion 22
targetSDKversion 32
compileSDKversion 33

Proguard Minify

If you use Android minify options, AVPro Video will be stripped out and will not work. The following options need to be added to your proguard configuration file (in Player Settings > Android > Publishing Settings > Build > Custom Proguard File) to prevent AVPro Video classes from being removed:

-keep class com.renderheads.AVPro.Video.** { *; }
-keep class com.google.android.exoplr2avp.** { *; }
-keep class com.twobigears.audio360.** { *; }

The above is included in /Assets/AVProVideo/Runtime/Plugins/Android/proguard-avprovideo.txt

OES Playback Path

Note

OES playback is not available in the trial version

For Android there is a special playback option called “Use Fast OES Path”. This option caters especially for VR where users are trying to get the highest possible frame rate and resolution out of the device (without it overheating at the same time). The option is available in the Platform Specific section of the MediaPlayer component:

alt_text

The OES path is not enabled by default because it requires some special care to be taken and can be tricky for beginners. When this option is enabled the Android GPU returns special OES textures (see EGL extension OES_EGL_image_external) that are hardware specific. Unfortunately Unity isn’t able to use these textures directly, so you can’t just map them to a material or UI. To use the texture a GLSL shader must be used. Unfortunately Unity’s GLSL support isn’t as good as its CG shader support so again this makes things more tricky. The GLSL compiler only happens on the device (not inside Unity) so errors in the shader can be difficult to debug.

We have included a version of the VR sphere shader that supports stereo videos as an example. Hopefully in the future we can improve the integration of these shaders so they aren’t such special cases. This playback path is much faster though, so is definitely worth exploring. Note that for VR stereo rendering, OES only currently supports multi-pass rendering path, and not single-pass or single-pass instanced.

Troubleshooting

Streaming

If you want to support streaming from URL don’t forget to set the “Internet Access” option in Player Settings to “require”
If you’re streaming on Android 9 or above and connecting to an HTTP stream, then you either need to switch to HTTPS stream, or enable cleartext support in the AndroidManifest.xml

java.lang.ClassNotFoundException / java.lang.NoSuchMethodError

Check whether you have Proguard minification enabled (see notes on Minify above) which may be over-optimising and stripping AVPro Video files
Check the Gradle build notes above

Collecting Logs

We often need to see the device logs to work out why something isn't working. For this the device should be connected via USB.
If you're using Android Studio then you can click on the Logcat tab and choose No Filters in the bar on the top right. You should see logs being produced and can copy-paste all of them into a text file.
Another useful tool on Windows is called mLogcat and is a GUI tool for monitoring and capturing logs from Android.
Alternatively the command-line tool "adb logcat" can be used from the Android SDK.