feat(mpv): Add Vulkan/HDR device compatibility check

Introduces a new feature to verify Vulkan and HDR display compatibility for MPV playback, guiding users to optimal settings and ensuring fallback to OpenGL if Vulkan is not verified.

Key changes:
* MPV Device Compatibility Check: Implemented a new preference and UI in Player Options settings to verify Vulkan and HDR display support.
* Dynamic Settings Display: Conditionally renders GPU API and HDR Output settings based on Vulkan verification status.
* Vulkan Fallback: Player logic now defaults to OpenGL if Vulkan is selected but not verified as compatible.
* Persistent Device Signature: Stores a device signature to avoid re-checking Vulkan compatibility on every launch.

Author: MakD

.gitignore .afinityignore.gitignore renamed to .afinityignore

@@ -1,3 +1,25 @@
+# AFinity Ignore Rules
+#
+# This file uses standard Git ignore patterns but is not
+# automatically recognized by Git.
+#
+# SETUP
+# Run the following command from the repository root:
+#
+#   git config --local core.excludesFile "$(pwd)/.afinityignore"
+#
+# Windows PowerShell:
+#   git config --local core.excludesFile "$((Get-Location).Path)/.afinityignore"
+#
+# This configures Git to read these rules for this repository.
+# Each contributor must run the setup command after cloning.
+#
+# IMPORTANT
+# - This file supplements any existing .gitignore rules.
+# - Git does not ignore files that are already tracked.
+# - The configuration is local and is not inherited by forks.
+
+
 # Built application files
 *.apk
 *.ap_

README.md

@@ -35,13 +35,14 @@ and podcasts, and direct media requests via Jellyseerr.
 ```bash
 git clone https://github.com/MakD/AFinity.git
 cd AFinity
+bash setup-git.sh
 ./gradlew assembleRelease
 ```
 
-> **Note:** Without a `key.properties` file in the project root, release builds are signed with the
-> debug key. They install fine, but can't update an official release — uninstall the official APK
-> first. To sign with your own key, create `key.properties` with `storeFile`, `storePassword`,
-> `keyAlias`, and `keyPassword` entries.
+AFinity uses a custom `.afinityignore` file for Git ignore patterns. `setup-git.sh` configures Git to use these rules for this repository only. This setup is required once per clone.
+
+
+> **Note:** Without a `key.properties` file in the project root, release builds are signed with the debug key. They install fine, but can't update an official release — uninstall the official APK first. To sign with your own key, create `key.properties` with `storeFile`, `storePassword`, `keyAlias`, and `keyPassword` entries.
 
 ## Initial Setup
 
@@ -183,6 +184,8 @@ directly in your browser without needing any technical knowledge.
 
 ### Code Contributions
 
+Before making changes, run `bash setup-git.sh` from the repository root to configure Git to use AFinity's custom `.afinityignore` rules. This setup is required once per clone.
+
 1. **Fork** the repository
 2. **Create** a feature branch (`git checkout -b feature/AmazingFeature`)
 3. **Commit** your changes (`git commit -m 'Add some AmazingFeature'`)

app/src/main/java/com/makd/afinity/data/repository/PreferencesRepository.kt

@@ -183,6 +183,12 @@ interface PreferencesRepository {
 
     fun getMpvHdrPeakDetectionFlow(): Flow<Boolean>
 
+    suspend fun setMpvDeviceCheckSignature(signature: String)
+
+    suspend fun getMpvDeviceCheckSignature(): String?
+
+    fun getMpvDeviceCheckSignatureFlow(): Flow<String?>
+
     suspend fun setPreferredAudioLanguage(language: String)
 
     suspend fun getPreferredAudioLanguage(): String

app/src/main/java/com/makd/afinity/data/repository/impl/PreferencesRepositoryImpl.kt

@@ -147,6 +147,7 @@ constructor(@param:AppPreferences private val dataStore: DataStore<Preferences>)
         val MPV_HDR_OUTPUT = stringPreferencesKey("mpv_hdr_output")
         val MPV_TONE_MAPPING = stringPreferencesKey("mpv_tone_mapping")
         val MPV_HDR_PEAK_DETECTION = booleanPreferencesKey("mpv_hdr_peak_detection")
+        val MPV_DEVICE_CHECK_SIGNATURE = stringPreferencesKey("mpv_device_check_signature")
         val MPV_VIDEO_OUTPUT = stringPreferencesKey("mpv_video_output")
         val MPV_AUDIO_OUTPUT = stringPreferencesKey("mpv_audio_output")
 
@@ -899,6 +900,18 @@ constructor(@param:AppPreferences private val dataStore: DataStore<Preferences>)
         }
     }
 
+    override suspend fun setMpvDeviceCheckSignature(signature: String) {
+        dataStore.edit { preferences -> preferences[Keys.MPV_DEVICE_CHECK_SIGNATURE] = signature }
+    }
+
+    override suspend fun getMpvDeviceCheckSignature(): String? {
+        return dataStore.data.first()[Keys.MPV_DEVICE_CHECK_SIGNATURE]
+    }
+
+    override fun getMpvDeviceCheckSignatureFlow(): Flow<String?> {
+        return dataStore.data.map { preferences -> preferences[Keys.MPV_DEVICE_CHECK_SIGNATURE] }
+    }
+
     override suspend fun setPreferredAudioLanguage(language: String) {
         dataStore.edit { preferences -> preferences[Keys.PREFERRED_AUDIO_LANGUAGE] = language }
     }

app/src/main/java/com/makd/afinity/data/repository/settings/PortablePreferences.kt

@@ -41,6 +41,7 @@ internal object PortablePreferences {
             "mpv_hdr_peak_detection",
             "mpv_video_output",
             "mpv_audio_output",
+            "mpv_device_check_signature",
         )
 
     val specs: List<PrefSpec> =

app/src/main/java/com/makd/afinity/player/mpv/MpvDeviceSupport.kt

@@ -0,0 +1,50 @@
+package com.makd.afinity.player.mpv
+
+import android.content.Context
+import android.content.pm.PackageManager
+import android.hardware.display.DisplayManager
+import android.view.Display
+
+data class MpvDeviceCapabilities(
+    val vulkanVersion: String?,
+    val vulkanSupported: Boolean,
+    val hdrTypes: List<Int>,
+)
+
+object MpvDeviceSupport {
+    // The bundled libplacebo (v7) rejects devices below Vulkan 1.2.
+    private const val MIN_VULKAN_VERSION = 0x402000
+    const val MIN_VULKAN_VERSION_LABEL = "1.2"
+
+    fun supportsVulkan(context: Context): Boolean =
+        context.packageManager.hasSystemFeature(
+            PackageManager.FEATURE_VULKAN_HARDWARE_VERSION,
+            MIN_VULKAN_VERSION,
+        )
+
+    fun capabilities(context: Context): MpvDeviceCapabilities =
+        MpvDeviceCapabilities(
+            vulkanVersion = vulkanVersion(context),
+            vulkanSupported = supportsVulkan(context),
+            hdrTypes = hdrTypes(context),
+        )
+
+    fun isVulkanVerified(capabilities: MpvDeviceCapabilities, savedSignature: String?): Boolean =
+        capabilities.vulkanSupported && savedSignature == signature(capabilities)
+
+    fun signature(capabilities: MpvDeviceCapabilities): String =
+        "vulkan=${capabilities.vulkanVersion ?: "none"};hdr=${capabilities.hdrTypes.isNotEmpty()}"
+
+    private fun vulkanVersion(context: Context): String? =
+        context.packageManager.systemAvailableFeatures
+            .firstOrNull { it.name == PackageManager.FEATURE_VULKAN_HARDWARE_VERSION }
+            ?.version
+            ?.let { "${(it ushr 22) and 0x7f}.${(it ushr 12) and 0x3ff}.${it and 0xfff}" }
+
+    private fun hdrTypes(context: Context): List<Int> {
+        val displayManager =
+            context.getSystemService(DisplayManager::class.java) ?: return emptyList()
+        val display = displayManager.getDisplay(Display.DEFAULT_DISPLAY) ?: return emptyList()
+        return display.mode.supportedHdrTypes.toList()
+    }
+}

app/src/main/java/com/makd/afinity/ui/player/PlayerViewModel.kt

@@ -69,6 +69,7 @@ import com.makd.afinity.data.models.media.AfinitySources
 import com.makd.afinity.data.models.media.AfinityTrickplayInfo
 import com.makd.afinity.data.models.player.AssRenderMode
 import com.makd.afinity.data.models.player.GestureConfig
+import com.makd.afinity.data.models.player.MpvGpuApi
 import com.makd.afinity.data.models.player.MpvHdrOutput
 import com.makd.afinity.data.models.player.PlaybackStats
 import com.makd.afinity.data.models.player.PlayerEvent
@@ -97,6 +98,7 @@ import com.makd.afinity.player.audiobookshelf.AudiobookshelfPlayer
 import com.makd.afinity.player.common.TrackMapping
 import com.makd.afinity.player.common.TrackSelection
 import com.makd.afinity.player.mpv.MPVPlayer
+import com.makd.afinity.player.mpv.MpvDeviceSupport
 import com.makd.afinity.ui.player.utils.VolumeManager
 import com.makd.afinity.util.NetworkConnectivityMonitor
 import com.makd.afinity.util.formatFileSize
@@ -859,7 +861,10 @@ constructor(
         mpvVideoOutputValue = mpvVideoOutput
 
         val bufferSizeMb = preferencesRepository.getBufferSizeMb()
-        val gpuApi = preferencesRepository.getMpvGpuApi()
+        val gpuApi =
+            preferencesRepository.getMpvGpuApi().let {
+                if (it == MpvGpuApi.VULKAN && !isVulkanVerified()) MpvGpuApi.OPENGL else it
+            }
         val hdrOutput = preferencesRepository.getMpvHdrOutput()
         val toneMapping = preferencesRepository.getMpvToneMapping()
         val hdrPeakDetection = preferencesRepository.getMpvHdrPeakDetection()
@@ -1999,6 +2004,22 @@ constructor(
         }
     }
 
+    private suspend fun isVulkanVerified(): Boolean =
+        try {
+            val savedSignature = preferencesRepository.getMpvDeviceCheckSignature()
+            withContext(Dispatchers.IO) {
+                MpvDeviceSupport.isVulkanVerified(
+                    MpvDeviceSupport.capabilities(context),
+                    savedSignature,
+                )
+            }
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Timber.e(e, "Failed to verify Vulkan support")
+            false
+        }
+
     private fun isDisplayHdr(): Boolean? =
         try {
             val displayManager = context.getSystemService(Context.DISPLAY_SERVICE) as DisplayManager