Skip to content

Home

Jump to bottom
joric edited this page Apr 22, 2026 · 320 revisions

Welcome to the Xplayer2 wiki! This is about XPlayer2 fork for Android TV. I use it with RayNeo Pocket TV and VITURE One Lite.

This fork originated from keypad support, because it's the primary (and sometimes only) input method on a TV.

Changes

  • Modified manifest, added leanback feature and leanback launcher intent to show launch icon on Android TV devices.
  • Added keypad support for file selector and player, Center toggles UI, Back hides UI, Left/Right rewinds video.
  • Added 2D/3D button to toggle hardware video modes for the connected glasses.

TODO

  • Show 3d movies as 2d (currently button only toggles hardware 3d mode for the VITURE glasses).
  • 3d UI support in SBS mode (double seekbar, duplicate buttons and everything).
  • Real-time 2d to 3d conversion with depth estimation as in Immersive 3D.

Pictures

Screenshot 2026-04-10 072710
Besides OU-SBS conversion, XPlayer2 also supports outer-clipped letterbox OU videos (Shift button to fix the image).

Building

Linux

I use WSL2 (Ubuntu) on Windows. Real Windows has multiple issues with submodules and backslashes in paths.

wsl --install -d Ubuntu --location E:\WSL\Ubuntu
sudo apt update
mkdir -p ~/Android/cmdline-tool
wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
sudo apt install unzip
unzip commandlinetools-linux-*.zip -d cmdline-tools
mv cmdline-tools/cmdline-tools cmdline-tools/latest
echo 'export ANDROID_HOME=$HOME/Android' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator' >> ~/.bashrc
source ~/.bashrc 
sudo apt install openjdk-17-jdk -y
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0" "ndk;27.0.12077973" "emulator"
sdkmanager --licenses
git clone --recurse-submodules https://github.com/joric/Xplayer2.git
cd ~/Xplayer2/
git checkout android-tv
curl -L -o viture_sdk.tar.xz https://static.viture.dev/external-file/sdk/viture_android_sdk_v1.0.7.tar.xz
tar -xf viture_sdk.tar.xz
mkdir -p app/libs
cp aar/VITURE-SDK-1.0.7.aar app/libs/

Use emulator on Windows from Android Studo -> More Actions -> Virtual Device Manager -> Create Device -> Google TV (Android 12). Add this to Windows ~/.wslconfig to see emulator adb over network:

[wsl2]
networkingMode=mirrored

Use adb logcat to view emulator logs. It should work immediately, if emulator is the only connected device.

If you're using CX file manager with the player, use this command to grant file permissions:

adb shell appops set com.cxinventor.file.explorer MANAGE_EXTERNAL_STORAGE allow

Install VSCode using code . in WSL console. Install Android Launcher extension and use Ctrl+Shift+P, Run & Stream Logs.

You can run it with all the messages to build manually, from VSCode terminal:

./gradlew :app:assembleDebug --stacktrace

Windows

This project was not Windows compatible, because there was a conflict with Windows paths. It also uses submodules (ffmpeg/media3) for some reason, though they could be just referenced and built via Android SDK. If you forgot to clone the submodules, use:

git submodule update --init --recursive

Do not edit local properties (they reset each time), add path to environment variables (needs restarting Android Studio):

setx ANDROID_SDK_ROOT "C:\Users\<your_user>\AppData\Local\Android\Sdk"

Android Studio launches emulator naturally. If you manage to make a project that builds for Windows, you can use:

gradlew.bat assembleDebug
gradlew.bat installDebug && adb shell am start -n com.your.project/.MainActivity

To fix illegal unicode escape sequence on Windows, add this to the root build.gradle.kts:

subprojects {
  tasks.withType<JavaCompile>().configureEach {
    doFirst {
      fileTree(rootDir).matching { include("**/build/generated/aidl_source_output_dir/**/*.java") }
        .forEach {
          val s = it.readText(); val r = s.replace('\\','/')
          if (r != s) it.writeText(r)
        }
    }
  }
}

You also would need to put VITURE-SDK-1.0.7.aar to app/libs. If the app doesn't run, use the sync button in the build console.

Releases

To build releases on GitHub with actions you would need secrets to sign the build (you don't need a Play Store account).

ANDROID_KEYSTORE_BASE64
ANDROID_KEYSTORE_PASSWORD
ANDROID_KEY_ALIAS
ANDROID_KEY_PASSWORD

To generate a key:

keytool -genkey -v -keystore my-release-keystore.jks -alias key-alias -keyalg RSA -keysize 2048 -validity 100000

Then Base64 it with base64 -w0 my-release-keystore.jks and use as BASE64 secret. Keystore and key passwords are matching. The key alias is set in keytool parameters. Then use GitHub repository settings to add secrets. Then just use tags to publish:

git tag v1.0.6-dev && git push origin --tags

Or you can simply create a new release with the corresponding tag, action will run and attach an apk to it.

VITURE

Latest release implements hardware 2D/3D switching. I used 1.0.7 SDK (1.0.1 crashes, newest SDK doesn't have JNI bindings):

Read the documentation on how to implement 2D/3D switching in your project. It's pretty easy. The call in question is:

public void onCheckedChanged(CompoundButton compoundButton, boolean b) {
    if (mSdkInitSuccess == Constants.ERROR_INIT_SUCCESS) {
        mArManager.set3D(b);
    }
}

Alternatives

XPlayer2 is essentially the only good open-source Android TV player with OU-SBS conversion. Other players worth noticing:

  • NOVA - SBS only, great OSD, sound boost, best player (letterbox frame in 3D is pitch black, not overexposed as on KODI).
  • KODI - SBS only (on Android). Can show 3D as 2D. Working TVDB v4 scraper, sound boost, excellent keyboard support.
  • VLC - SBS only, classic and very popular player, generally not recommended, because there is NOVA and KODI.
  • DDDPlayer - can play OU as SBS, very simple, made for Cardboard VR (fisheye by default), open source.
  • DiME 3D Player - plays OU as SBS, thick grey outline, lacks keyboard support (no seeking with the keyboard).
  • VaR's VR Video Player - plays OU as SBS, a lot of formats and buttons, but no keyboard support at all, made with Unity.
  • mpv-android - libmpv-based barebone player, poor controls but can convert OU to SBS with some tinkering.

MPV Settings

MPV uses mpv.conf (can be edited in the extended settings menu). To convert OU to SBS simply add this:

vf=stereo3d=abl:sbsl

To use hardware decoding and custom aspect ratio:

hwdec=mediacodec
vf=stereo3d=abl:sbsl,setdar=16/9

It also supports shaders, you have to load a shader file:

glsl-shaders="/storage/emulated/0/Android/media/is.xyz.mpv/sbs.glsl"
aspect-ratio-override=0.5

Example sbs.glsl file (use adb push sbs.glsl /storage/emulated/0/Android/media/is.xyz.mpv/, the only readable dir):

//!HOOK MAIN
//!BIND HOOKED
//!DESC OU to SBS (simple)
vec4 hook() {
    vec2 pos = HOOKED_pos;
    if (pos.x < 0.5) {
        vec2 uv = vec2(pos.x * 2.0, pos.y * 0.5);
        return HOOKED_tex(uv);
    } else {
        vec2 uv = vec2((pos.x - 0.5) * 2.0, 0.5 + pos.y * 0.5);
        return HOOKED_tex(uv);
    }
}

You can also write your own shaders, like 360 panoramas, but there's no variable binding for controls.

Air Mouse

RayNeo Pocket TV (armeabi-v7a) supports Air Mouse in the accessibility settings, but it's borderline impossible to use. It switches off when it's needed the most - during virtual keyboards. Neither "LeanKey Keyboard" nor "Keyboard for Android TV" by NDC Solution (1.4.3.190711) fixes this behavior.

References

Clone this wiki locally