Create a Compatibility Matrix & User-Reporting Template (Based on Key Features) #350
Description
As LibrePods continues to grow across different Android versions, devices, and AirPods models, it’s becoming increasingly important to have a clear overview of what works where, especially since the project already implements a wide range of features (as listed in the README).
Right now, many issues arise from device-specific behaviour or incomplete support on certain AirPods generations. A structured Compatibility Matrix, combined with a User-Reporting Template, would make it much easier for users to self-diagnose, and for maintainers to identify recurring patterns.
🎯 Why this is useful
-
Users can quickly check compatibility before opening an issue.
-
Maintainers get consistent, structured data in bug reports.
-
Makes it easier to identify trends such as:
- “ANC not working on AirPods Pro 2 + Android 14 on Samsung devices”
- “Case battery not reported on certain chipsets”
-
Helps steer development by highlighting where gaps exist.
📘 Incorporating the Project’s Key Features
The README lists the following key features:
- Automatic Ear Detection (AED)
- Automatic ANC and Transparency Mode Control
- Battery Level and Case Detection
- Double/Triple Tap Gesture Support
- Spatial Audio Support (if applicable)
- Device Status Reporting
- AirPods Firmware Information
- Adaptive Noise Control (on supported models)
To help users understand which of these work on their setup, the compatibility matrix should reflect the support status of each feature per:
- Device model
- Android version
- Root / Magisk / LSPosed / rootless status
- AirPods model (Gen1/2/3, Pro/Pro2, Max)
- LibrePods version
✅ Suggested Actions
⬜ 1. Add a Compatibility Matrix to the documentation
The matrix could cover the following:
Columns (features):
- Automatic Ear Detection
- ANC / Transparency Controls
- Automatic Mode Switching
- Battery Levels (L / R / Case)
- Gesture Controls
- Spatial Audio Indicators / Settings
- Firmware Info Support
- Adaptive Noise Control
- L2CAP-dependent features
- Root-only enhancements
Rows (environment):
- Phone model
- Chipset
- Android version
- Root/no-root
- AirPods model
A file such as:
/docs/compatibility.md
or a GitHub Wiki page would work well.
⬜ 2. Add a User-Reporting Template for issue submissions
A structured template will ensure bug reports are complete and actionable.
Suggested template:
### Device & Environment
**Device model:**
**Chipset (if known):**
**Android version:**
**Root status:** (Root / Magisk / LSPosed / Rootless)
**Bluetooth stack modifications (if any):**
**LibrePods version:**
### AirPods Information
**AirPods model:**
**Firmware version (if shown):**
### Expected behaviour:
<describe what you expected to happen>
### Actual behaviour:
<describe what happened instead>
### Features affected:
- [ ] Automatic Ear Detection
- [ ] ANC / Transparency
- [ ] Gesture controls
- [ ] Battery reporting
- [ ] Spatial Audio features
- [ ] Firmware info
- [ ] Adaptive Noise Control
- [ ] Other:
### Logs (if available):
<attach or paste>
⬜ 3. Add a brief “How to collect logs” guide
This will reduce repetitive questions and improve debugging quality.
📌 Closing Thoughts
By aligning the Compatibility Matrix with the README’s key feature list, users and contributors get a clear, accurate picture of real-world support. It will also reduce friction in bug reports and make the maintenance burden lighter overall.