Android Bluetooth Audio Guardian

A conservative KernelSU and Magisk module that may reduce intermittent Bluetooth audio crackles caused by scheduler contention on compatible rooted Android devices.

This is not a codec tweak or a universal audio fix. Compatibility is determined by Android scheduler interfaces, not by device brand or chipset.

Tested configuration

The initial release was developed and tested on:

• Nothing Phone (1), codename Spacewar
• Qualcomm Snapdragon 778G+
• crDroid 12 / Android 16
• KernelSU Next
• Galaxy Buds2 Pro using AAC software encoding
• ViPER4Android RE Fork in the software-A2DP effect path

Other devices are experimental until users report results.

Compatibility model

The module does not use a device allowlist. Installation is permitted when all required runtime capabilities are present:

• KernelSU, KernelSU Next, or Magisk root module support
• A writable /dev/cpuctl/rt/tasks interface
• A writable /dev/cpuctl/rt/cpu.uclamp.min interface
• Android audio and Bluetooth processes whose names match or are added to config.conf

/dev/cpuctl/rt/cpu.uclamp.latency_sensitive is used when available but is optional.

This design is chipset-independent. Qualcomm, MediaTek, Exynos, Tensor, Unisoc, and other platforms may be compatible if their ROM and kernel expose the required scheduler interfaces. A matching chipset alone does not guarantee compatibility because vendors and custom ROMs can use different cgroup layouts, task profiles, SELinux rules, and service names.

The installer aborts without making changes when the required scheduler interfaces are missing or not writable.

What it does

• Keeps configured Android audio, audio HAL, and Bluetooth processes in the ROM's existing cpu:/rt cgroup.
• Protects only audio-related threads in configured media applications.
• Restores a modest 20% utilization floor on the existing RT CPU cgroup.
• Enables the existing RT latency-sensitive flag when the ROM exposes it.
• Reapplies the profile every 10 seconds because Android may move tasks during app, route, screen, camera, and notification transitions.

What it does not do

• It does not change Bluetooth codecs, sample rates, bit depth, or quality settings.
• It does not enable Bluetooth A2DP hardware offload.
• It does not change audio HAL period sizes or undocumented vendor properties.
• It does not alter ZRAM, CPU governors, GPU settings, nice values, or realtime scheduling policies.
• It does not install, remove, or modify ViPER4Android or Dolby modules.
• It does not claim to repair radio interference, firmware bugs, or hardware faults.

Why this approach

On the tested Spacewar build, Bluetooth A2DP hardware offload eventually caused silent playback and bypassed the ViPER4Android Bluetooth effect path. The software AAC path remained functional, but app launches, screen wakes, camera activity, notifications, and USB connection events could briefly delay the audio pipeline.

Moving the complete media application into the RT cgroup reduced crackles but unnecessarily protected unrelated networking, UI, and cache threads. This module instead protects the core system audio pipeline and selected playback-related threads.

Android officially supports vendor-defined cgroup layouts and task profiles, so the exact paths and process behavior can vary between ROMs. See the AOSP cgroup abstraction documentation.

Installation

1. Download the release ZIP from the GitHub releases page.
2. Make a current boot image backup and confirm that ADB root recovery is available.
3. Install the ZIP from KernelSU, KernelSU Next, or Magisk.
4. Read the installer's capability-check result.
5. Reboot.
6. Start Bluetooth playback and use the module action button to inspect status or immediately reapply the profile.

Do not continue using the module if boot, Bluetooth, calling, or audio behavior becomes abnormal. Disable or remove it in the root manager and reboot.

Configuration

Edit config.conf in /data/adb/modules/android_bt_audio_guardian/:

CHECK_INTERVAL_SECONDS=10
RT_UCLAMP_MIN=20.00
CORE_AUDIO_PROCESSES="audioserver"
AUDIO_HAL_PROCESSES="android.hardware.audio.service android.hardware.audio.service-aidl"
BLUETOOTH_PROCESSES="com.android.bluetooth"
MEDIA_PACKAGES="com.spotify.music"

Process and package names are separated by spaces. Add the audio HAL process used by your ROM if it is not already listed. Only recognized playback-related thread names inside media applications are protected.

Restart the guardian after configuration changes:

su -c '/system/bin/sh /data/adb/modules/android_bt_audio_guardian/guardian.sh stop'
su -c '/system/bin/sh /data/adb/modules/android_bt_audio_guardian/guardian.sh start'

Bluetooth absolute volume

The module never changes Bluetooth absolute volume. On the tested Galaxy Buds2 Pro, enabling Developer options > Disable absolute volume did not eliminate the issue and was followed by additional crackles, so the option was returned to its default state.

ViPER4Android and Dolby

The module does not modify audio effects. It remained compatible with the tested ViPER4Android RE Fork software-A2DP path. ViPER4Android and Dolby are not included and are not required.

Status and diagnostics

adb shell su -c '/system/bin/sh /data/adb/modules/android_bt_audio_guardian/guardian.sh status'
adb shell su -c 'tail -n 100 /data/adb/modules/android_bt_audio_guardian/guardian.log'
adb shell su -c 'cat /proc/$(pidof audioserver)/cgroup'

Useful compatibility checks before installation:

adb shell su -c 'ls -l /dev/cpuctl/rt/tasks /dev/cpuctl/rt/cpu.uclamp.min'
adb shell su -c 'pidof audioserver com.android.bluetooth android.hardware.audio.service'

Rollback

Disable or uninstall the module in KernelSU/Magisk and reboot. A reboot is required because Android task cgroup membership is runtime state.

Emergency rollback from ADB:

adb shell su -c 'touch /data/adb/modules/android_bt_audio_guardian/disable'
adb reboot

Reporting compatibility

When opening a compatibility report, include:

• Device model and codename
• SoC and Android/ROM version
• Root solution and version
• Bluetooth device and active codec
• Output of the status and compatibility-check commands
• Whether the issue improved, remained unchanged, or worsened

Do not upload full logs until you have removed account names, Bluetooth addresses, device identifiers, and other personal data.

Known limitations

• The first release is validated on one device and ROM combination.
• Android may briefly move a newly created thread before the next guardian interval.
• Devices using only cgroup v2 or a different cpuctl layout are not supported by this release.
• SELinux or vendor task-profile rules may prevent or repeatedly override task movement.
• Audio HAL and media thread names can differ by vendor and application.
• Bluetooth LE Audio, calls, hearing aids, and automotive audio paths are untested.
• The tested ROM reports no software Dynamic Audio Buffer support, so the module does not configure it.
• Bluetooth A2DP hardware offload is intentionally left unchanged.

Building

On Linux or macOS:

./build.sh

On Windows PowerShell:

./build.ps1

The installable ZIP and SHA-256 checksum are written to dist/.

References

• AOSP cgroup abstraction layer
• Magisk module developer guide
• KernelSU module guide

License

MIT